README

这是一个为 Symfony v2.2+ 提供的 Bundle，它提供了一个 Bootstrap (v2.x 或 v3.x) Typeahead 小部件，用于表单中。该 Bundle 中使用的 Typeahead 组件是原始的 Bootstrap v2.3 Typeahead 库，并进行了一些增强。

更新：如果您在 composer.json 中指向 dev-master，并且此 Bundle 停止工作，请将版本更改为 "^1.*"，然后运行 composer update lifo/typeahead 以更新您的项目。

如果您使用的是 Bootstrap v2.x，则必须使用此 Bundle 的 1.* 版本。
如果您使用的是 Bootstrap v3.x，则必须使用此 Bundle 的 2.* 版本。

注意：此 Bundle 不使用较新的 Twitter/Typeahead.js JavaScript 库。

增强的 Typeahead 功能

此 Bundle 为原始 Bootstrap typeahead JavaScript 库添加了一些增强功能

支持 JSON 对象
缓存结果
延迟 AJAX 请求以减少服务器请求
正确处理鼠标粘贴
包括一个 AJAX Loader 图标
支持非实体查找
支持通过自定义回调函数的非 AJAX 加载

截图

此示例显示了一个单行输入的表单字段。

此示例显示了一个可以输入多个名称的表单字段。点击名称链接将删除实体。后端中的实体实际上是 ArrayCollection，并自动允许从列表中添加/删除实体。

安装方法

注意： 此 Bundle 要求在您的环境中安装 jQuery 和 Bootstrap，但不直接包含它们。 我建议使用 mopa/bootstrap-bundle，它可以帮助您完成此操作。

将 lifo/typeahead-bundle 添加到项目 composer.json 文件的 "requires" 部分，这可以通过在项目目录中运行 composer 命令自动完成
```
composer require lifo/typeahead-bundle
```
或手动编辑 composer.json 文件
```
{
    // ...
    "require": {
        // ...
        "lifo/typeahead-bundle": "^2.0"
    }
}
```
在项目根目录中运行 composer update

更新项目 app/AppKernel.php 文件，并将此 Bundle 添加到 $bundles 数组中

$bundles = array(
    // ...
    new Lifo\TypeaheadBundle\LifoTypeaheadBundle(),
);

将 @lifo_typeahead_js 添加到您的 Assetic javascripts 块中。类似于下面的块。您的实际设置可能不同。确保在 jQuery 和 Bootstrap 库之后包含它。
```
{% javascripts filter='?yui_js' output='js/site.js'
    '@lifo_typeahead_js'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
```

将 @lifo_typeahead_css 添加到您的 Assetic stylesheets 块中。类似于下面的块。您的实际设置可能不同。

{% stylesheets filter='cssrewrite,?yui_css' output='css/site.css'
    '@lifo_typeahead_css'
-%}
    <link href="{{ asset_url }}" type="text/css" rel="stylesheet" />
{% endstylesheets %}

如果您不使用 Assetic，则必须手动将 JavaScript 和 CSS 文件包含到项目中。

<link href="{{ asset('bundles/lifotypeahead/css/typeaheadbundle.css') }}" type="text/css" rel="stylesheet" />
<script src="{{ asset('bundles/lifotypeahead/js/bootstrap-typeahead.js') }}"></script>
<script src="{{ asset('bundles/lifotypeahead/js/typeaheadbundle.js') }}"></script>

使用方法

使用 typeahead 控件非常简单。下面概述了可用的选项

$builder->add('user', 'entity_typeahead', array(
    'class'  => 'MyBundle:User',
    'render' => 'fullname',
    'route'  => 'user_list',
));

选项

class 是您的实体类。如果 null（或未指定），则从您的控制器 AJAX 响应返回的项目不必是实体。如果不为空，则使用该类将项目映射到您的数据库实体。
source 是要调用的函数的名称，用于收集要显示的项目。此属性或 route 必须指定。原型为：function(query, process)，其中 process 是您在获取到匹配项列表后应调用的回调函数。它期望一个平面字符串数组，用于渲染下拉菜单（不是 {id:'...', value:'...'} 对象！）。下面有示例，了解更多信息。
route 是获取实体的路由名称。匹配路由的控制台将通过 POST 接收以下参数
- query 根据该查询字符串筛选结果。
- limit 返回的最大结果数。
- render 配置的 render 名称。这是您应在 AJAX 响应中设置 value 属性的内容。
- property 配置的 property 名称。通常这是 id。这是您应在 AJAX 响应中设置 id 属性的内容。
route_params 要传递给 route 的额外参数。
minLength 触发 AJAX 请求之前所需的最小字符数。
items 一次最多显示的项目数（默认：8）
delay 在触发 AJAX 之前的延迟时间（毫秒）（默认：250）
spinner 用于加载旋转器时要使用的类字符串（默认："glyphicon glyphicon-refresh spin"）Font-Awesome 示例："fa fa-refresh fa-spin fa-fw"
multiple 如果为 true，小部件将允许选择多个实体。一次一个。此特殊模式将在类型提示小部件下方创建一个无序列表来显示选定的实体。
callback 当选择项目时被调用的回调函数（或字符串）。原型：function(text, data)，其中 text 是所选项目的标签，data 是服务器返回的 JSON 对象。
render 是要在类型提示输入中显示的实体属性。这用于将初始值（值）渲染到小部件中。一旦用户开始输入，渲染的响应将取决于使用的 route 或 source。

AJAX 响应

控制台应返回以下格式的 JSON 数组。注意：id 和 value 属性是必需的，但您可以包含其他属性。

[
  { id: 1, value: 'Displayed Text 1' },
  { id: 2, value: 'Displayed Text 2' }
]

注意：如果您使用 null 的 class 选项，则您的 JavaScript 数组应返回相同的 id 和 value。例如

[
  { id: 'Result 1', value: 'Result 1' },
  { id: 'Result 2', value: 'Result 2' }
]

如果您不为 id 和 value 返回相同的字符串，您的 UI 中将出现混乱的结果。

自定义 Source 回调

以下是一个自定义 source 回调的示例。此示例模拟了使用 route 选项时的相同结果。

function get_users(query, process) {
    $.post('/mysite/lookup/users', {query: query}, 'json')
        .success(function (data) {
            // must convert the data array into a flat list of strings. 
            // If your lookup function already returns a flat list, then $.map() is not needed.
            process($.map(data, function(a){
                return a.value;
            }));
        });
}

$builder->add('user', 'entity_typeahead', array(
    'class'  => 'MyBundle:User',
    'render' => 'fullname',
    'source' => 'get_users', // a function name in the global javascript "window" object 
));

模板

您的表单模板可能看起来像这样 （上面的截图使用了这个模板片段）。 注意： widget_addon 属性是 mopa/bootstrap-bundle 属性。

{{ form_row(form.name) }}
{{ form_row(form.owner, { attr: { placeholder: 'Search for user ...'}, widget_addon: {type: 'append', 'icon': 'user'}}) }}
{{ form_row(form.users, { attr: { placeholder: 'Add another user ...'}, widget_addon: {type: 'append', 'icon': 'user'}}) }}

注意

此包以标准的 Symfony 风格渲染其表单元素。您需要覆盖表单块以应用适当的 Bootstrap 样式。我强烈建议使用类似 mopa/bootstrap-bundle 的东西，它会自动为您覆盖 Symfony 表单模板，使用适当的 Bootstrap 版本。

ruben-ruvic / typeahead-bundle

维护者

详细信息