seblhaire/autocompleter

A Laravel 库，使用 Javascript JQuery 脚本为表单添加具有自动完成功能的输入

维护者

详情

github.com/seblhaire/autocompleter

主页

源码

问题

安装: 36

依赖: 1

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

开放问题: 0

1.5.0 2024-03-13 18:13 UTC

Requires

MIT 1d8576f7e9d664df6b9af31cc807c5b8b8b7d846

  • Sébastien L'haire <sebastien.woop@lhaire.org>

This package is auto-updated.

Last update: 2024-09-13 19:16:29 UTC

README

作者 Sébastien L'haire

A Laravel 库，使用 Javascript JQuery 脚本为表单添加具有自动完成功能的输入。

它使用

  • 基于 jQuery Javascript 框架的自动完成脚本。
  • Bootstrap 4 / 5 CSS 框架。

Autocompleter

Autocompleter with result list

演示网站在此处。

安装

  1. composer require seblhaire/autocompleter
  2. Composer 会自动将包与 Laravel 链接。但您还可以明确地将提供者添加到您的 config/app.php
  'providers' => [
    ...
      Seblhaire\Autocompleter\AutocompleterServiceProvider::class,
      ...
    ],
    'aliases' => [
        ...
        "AutocompleterHelper" => Seblhaire\Autocompleter\AutocompleterHelper::class
      ]
  1. 发布包（可选）。
$ php artisan vendor:publish
  1. 有关 JavaScript 和样式表的说明，请参阅下一节。

JavaScript 和样式表

在网页上，每个 JS 库和 CSS 样式表都可以单独链接。如果您选择这种方式，首先下载并安装上述库。然后按照上述说明发布包文件，并在模板中放置以下标签

<script type="text/javascript" src="js/vendor/seblhaire/autocompleter/autocompleter.js"></script>
<link rel="stylesheet" type="text/css" property="stylesheet" href="css/vendor/seblhaire/autocompleter/autocompleter.css"/>

但网站通常使用许多库和样式表，浏览器必须下载许多文件，才能正确渲染网站。现代网站包含一个单一的压缩 JavaScript 文件，该文件连接必要的脚本；样式表也遵循相同的原则。使用 Laravel，您可以使用 Laravel Mix 编译文件。

使用 NPM 包管理器： npm install bootstrap jquery

然后您的 js 源文件应该是这样的

global.jQuery = require('jquery');
var $ = global.jQuery;
var jQuery = global.JQuery;
window.$ = $;
window.jQuery = jQuery;
require('bootstrap');
require('../../vendor/seblhaire/autocompleter/resources/js/autocompleter.js');

对于您的样式表

@import '~bootstrap/scss/bootstrap';

@import "../../vendor/seblhaire/autocompleter/resources/css/autocompleter";

配置文件

自动完成库可自定义。默认值可以在配置文件中更改，也可以通过在 Facade 函数中传递选项来更改（见下一节）。如果您想修改默认配置文件，发布包文件并访问 config/autocompleter.php。

用法

自动完成包附带一个简单的 Facade。

AutocompleterHelper::init

初始化一个自动完成对象，该对象可以传递到视图中。

AutocompleterHelper::init($inputid, $labeltext, $url, $options) 其中

  • $inputid：获取自动完成的 <input> 标签的 id。
  • $labeltext：输入标签，
  • $url：用于加载数据的路由。如果为静态数据，则设置空值。
  • $options：选项数组。
    • 'labelclass'：输入标签的类。默认无；
    • 'helpclass'：帮助文本类。默认：'autocompletehelp'；
    • 'helptext'：输入下方的帮助文本。文本可以是字符串或翻译键。见 下面，
    • 'divclass'：主要 <div> 类。默认："form-group"
    • 'inputclass'：自动完成 <input> 字段的类。默认：'form-control'；
    • 'resultdivclass'：包含结果列表的 <div> 的类。默认：'sebautocomplete'；
    • 'resultlistclass'：结果列表 <ul> 元素的类。默认：'list-group'；
    • 'resultlistclassitem'：列表项 <li> 元素的类。默认：'list-group-item'；
    • 'highliteclasses'：高亮显示列表中的搜索词的 <span> 的类。默认：'sebautoloadhighlite'；
    • 'activeitem'：高亮显示当前选中 <li> 元素的类。默认：'active'；
    • 'id_field'：结果行中包含数据标识符或键的字段名称。默认：'id'，
    • 'id_included'：id字段（参见上一行）必须添加到结果中。默认：true；
    • 'list_field'：结果行中包含要显示在列表中的文本的字段名称。默认：'listfield'；
    • 'encoding'数据字符编码。默认 'utf8'；
    • 'maxresults'：最大结果数。默认：6；
    • 'minsearchstr'：启动自动完成的最小搜索字符串长度。默认：1；
    • 'callback'：在被选值之后要调用的函数名称。

总结一下，在您的控制器中插入

$ac = AutocompleterHelper::init(
   'autocompleter1',
   'Countries',
   route('autocompletesearch'), // route called when typing in input
   [
    'callback' => 'output'
 ]);
 ...
 return view('autocompleter', [
      ...
     'ac' => $ac,
     ...
 ]);

在您的blade模板中，在您想要自动完成器出现的位置插入以下内容

{!! $ac !!} 或 {!! $ac->output() !!}

输出方法

output()

此方法 output() 打印标签并输出自动完成器初始化脚本。它使用上述方法，这些方法可以用于在其他小部件中集成自动完成器，或按照您的意愿组织代码。

printDiv()

此方法打印主要的 <div>。它使用 printInsideDiv() 和 printHelp() 方法。

printInsideDiv()

打印包含标签、表单输入和结果列表的 <div>。该容器是必要的，用于定义固定宽度。它使用 printLabel()、printInput() 和 printResultDiv() 方法。

printHelp()

在输入行下方打印帮助文本。

printResultDiv()

打印包含建议列表的结果容器。

printLabel()

打印自动完成器标签。

printInput()

打印自动完成器输入字段。

printJsInit()

打印用于初始化自动完成器的JavaScript代码。

Utils::highlite($string, $search, $classes)

接受一个字符串，在它中搜索一个子字符串并突出显示相应的块。

Utils::highlite($string, $search, $classes) : string

其中

  • $string 是要突出显示的字符串；
  • $search 是要搜索的子字符串；
  • $classes 是要插入到突出显示字符串中的 <span> 标签的类。

该函数返回突出显示的字符串。

搜索函数

您必须在控制器中构建一个简单的方法，该方法将被调用来更新结果列表。以下是一些要求

  1. 您的路由必须接受POST方法；
  2. 自动完成器对象中只构建了两个参数；
    • 'search' 包含输入中的当前字符串；
    • 'maxresults' 是自动完成器可接受的最大结果数的整数。我们提供了一个请求模型 AutocompleterRequest 来执行表单验证。
  3. 该方法必须返回一个包含单个字段名为 'res' 的json对象，该字段包含结果行数组。
  4. 结果行是一个数组，必须至少包含以下字段
  • 一个字段，其键对应于配置值 id_field（参见上述内容）（config('autocompleter.highliteclasses')）；
  • 一个字段，其键对应于配置值 list_field，包含自动完成器结果列表的文本。如果配置中的 id_included 的值为 true，自动完成器对象将自动添加 id_field 的值。在此字段中，您可以使用上述提到的函数 Utils::highlite。总结一下，以下是一个完整的示例
use Seblhaire\Autocompleter\AutocompleterRequest;
...
public function search(AutocompleterRequest $request){
  $search = $request->input('search');
  $countries = collect(Countries::getList())->filter(function($data) use ($search){ //search in country list
    return (mb_stripos($data['code'], $search) !== false) || (mb_stripos($data['country'], $search) !== false);
  })->take($request->input('maxresults'));
  $res = [];
  if (count($countries) > 0){
    foreach  ($countries as $country){
      $res[] = [
        config('autocompleter.id_field') => $country['code'],
        'country' => $country['country'], // other value available
        config('autocompleter.list_field') => Utils::highlite($country['code'] . ' : ' . $country['country'], $request->input('search'), config('autocompleter.highliteclasses'))
      ];
    }
  }
  return response()->json(['res'  => $res]);
}

翻译键

Laravel 在进程的早期就加载配置文件。因此，配置文件不能包含 __('translation.key')。为了解决这个问题，我们创建了一个助手，可以直接打印字符串或将翻译键发送到翻译助手。翻译键可以由字符 # 分隔。例如："#autocompleter::messages.autocompleterhelp#"。原始翻译存储在 vendor/seblhaire/autocompleter/resources/lang 下。如果您发布了包文件，您可以在 resources/lang/vendor/autocompleter/ 中找到翻译。

请随意将键翻译成您的语言，并将其发送给作者或在GitHub上发起合并请求。

有疑问吗？有贡献吗？

请随时向作者发送功能请求或合并请求，或者简单地提出问题。