typeahead插件基础知识

罗金林

2023-12-01

翻译自：https://github.com/twitter/typeahead.js/blob/master/doc/jquery_typeahead.md

jQuery#typeahead
对于typeahead.js UI组件可以作为一个jQuery插件，它负责展示提示和处理DOM交互。

特征

向终端用户展示提示
显示顶级建议做为提示（即背景文本）
支持自定义模板使前端UI更加的灵活
能很好的使用RTL语言和输入法编辑器
高亮显示查询查询到的匹配项
触发自定义事件以鼓励可扩展性

API
jQuery#typeahead(options, [*datasets])
jQuery#typeahead(‘val’)
jQuery#typeahead(‘val’, val)
jQuery#typeahead(‘destroy’)
jQuery.fn.typeahead.noConflict()

jQuery#typeahead(options, [*datasets])

对于一个给定的input[type=”text”]，使用typeahead功能，options是一个用于配置选项的哈希，指的是为更多的信息关于可用的配置选项，随后的争论是(*datasets)，是个人选择的哈希值的数据集，有关数据集的更多细节，参考Datasets。

$('.typeahead').typeahead({
  minLength: 3,
  highlight: true
},
{
  name: 'my-dataset',
  source: mySource
});

jQuery#typeahead(‘val’)

返回typeahead当前的值，该值是用户输入到input元素中的文本。

var myVal = $('.typeahead').typeahead('val');

jQuery#typeahead(‘val’, val)

设置typeahead的值，这应该代替jQuery#val。

$('.typeahead').typeahead('val', myVal);

jQuery#typeahead(‘open’)

打开建议的菜单。

$('.typeahead').typeahead('open');

jQuery#typeahead(‘close’)

关闭建议的菜单。

$('.typeahead').typeahead('close');

jQuery#typeahead(‘destroy’)

删除typeahead 功能，并将其input元素恢复到原来的状态。

$('.typeahead').typeahead('destroy');

jQuery.fn.typeahead.noConflict()

返回一个typeahead插件的引用，并且还原jQuery.fn.typeahead到以前的值，可以用来避免命名冲突。

var typeahead = jQuery.fn.typeahead.noConflict();
jQuery.fn._typeahead = typeahead;

Options

当初始化typehead时，有许多选项可以配置。

highlight – 如果为true,提出建议时，模式匹配当前的查询文本节点将被包裹在一个强大的元素的类集为{ { classNames.highlight} }的类名称。默认为false。

hint – 如果为false,Typeahead不会显示提示。默认为true。

minLength – 建议开始呈现之前所需的最小字符长度，默认是1。

classNames – 用于重写所使用的默认类名，查询 Class Names获得更多的信息。

Datasets

一个typeahead是由一个或者多个字符集组成，当用户修改typeahead的值时，每个数据集将会尝试为新值提示。

对于大多数用例，一个数据集应该足够了，只有在场景中，您希望根据一些特定关系将呈现的建议分组，您需要使用多个数据集。例如，在twwiter.com,搜索typeahead组结果为最近的搜索趋势，占–将使用多个数据集的一个很好的用例。

可以使用以下选项来配置数据集：

1.source-建议支持的数据源，期望拥有签名函数(query, syncResults, asyncResults)，syncResults 应同步调用建议和asyncresults应该叫建议计算异步(e.g. suggestions that come for an AJAX request)。source 也可以是一个Bloodhound实例，必须的。

2.async-如果有期望的异步建议让我们的数据集知道，如果没有设置，这些信息是从源签名中推断出来的。如果原函数需要3个参数，async将会设为true。

3.name - 数据集的名称，这将附加到{{classNames.dataset}}上，以形成包含DOM元素的类名。必须只包含下划线、破折号、字母（A-Z），数字，默认为随机数。

4.limit - 要显示的建议的最大数目，默认值是5。

5.display -对于给定的建议，确定它的字符串表示形式，在选择提示后，将在设置输入控件的值时使用此选项。可以是键字符串，也可以是将建议对象转换为字符串函数，默认建议字符串。

6.templates -在呈现数据集时使用模板散列，注意预编译模板函数接受一个JavaScript对象作为其第一个参数并返回一个HTML字符串。
。notFound -当给定的查询提示0条时建议使用。可以是一个HTML字符串也可以是一个预编译的模板。如果它是一个预编译模板，通过上下文可以包含查询。
。pending -当呈现的同步建议时0个，那么异步建议是可预期的。可以是一个HTML字符串也可以是一个预编译的模板，如果是一个预编译模板，通过上下文可以包含查询。
。header-当提示出现时将会展示在数据集的顶部，可以是一个HTML字符串也可以是一个预编译的模板，如果是一个预编译模板，通过上下文可以包含查询和提示。
。footer-当提示出现时将会呈现在数据集的低部，可以是一个HTML字符串也可以是一个预编译的模板，如果是一个预编译模板，通过上下文可以包含查询和提示。
。suggestion -用于展示单个提示，如果设置了，这是一个预编译模板，关联的建议对象将作为上下文，默认值是display，被包在div标签中。

Custom Events

以下的事件可以触发输入元件的生命周期中typeahead。

typeahead:active：当typeahead 转换为活动（active）状态时触发。
typeahead:idle：当typeahead 转换为空闲（idle）状态时触发。
typeahead:open：当结果容器打开时触发。
typeahead:close：当结果容器关闭时触发。
typeahead:change：本机更改事件的标准化版本。当输入失去焦点时触发，并且值从原来输入到失去焦点后发生了变化。
typeahead:render：当为数据集提供提示时触发，将用4个参数调用事件处理程序：jQuery事件对象，展示提示，指示建议是否异步获取的标志，呈现的数据集发生变化。
typeahead:select：当提示被选中时触发，将用2个参数调用事件处理程序，jquery事件对象和被选中的提示对象。
typeahead:autocomplete：当自动完成时触发，将用2个参数调用事件处理程序：jquery事件对象和提示的事件对象，用于自动完成。
typeahead:cursorchange：当结果容器游标移动时发生变化，将用2个参数调用事件处理程序：jquery事件对象和被移动到的事件对象。
typeahead:asyncrequest：当一个异步请求提示发送时触发，将用3个参数调用事件处理程序：jquery事件对象、当前的查询，和属于异步请求数据集的名称。
typeahead:asynccancel：当异步请求关闭时触发，将用3个参数调用事件处理程序，jquery事件对象，当前的查询，和属于异步请求数据集的名称。
typeahead:asyncreceive：当异步请求完成时触发，将用3个参数调用事件处理程序，jquery事件对象，当前的查询，和属于异步请求数据集的名称。

使用示例：

$('.typeahead').bind('typeahead:select', function(ev, suggestion) {
  console.log('Selection: ' + suggestion);
});

注：每个事件都不能提供相同的参数。有关每个事件的参数列表的详细信息，请参见上面的事件描述。

Class Names

input-初始化一个typeahead添加到input组件，默认是tt-input。
hint -添加到输入提示框，默认是tt-hint。
menu -添加到菜单元素，默认是tt-menu。
dataset -添加到数据集元素，默认是tt-dataset。
suggestion -添加提示元素，默认是tt-suggestion。
empty -添加到不包含内容的菜单元素中，默认是tt-empty。
open -打开时添加到菜单元素，默认是tt-open。
cursor -当菜单光标移动到提示时添加到建议元素，默认是tt-cursor。
highlight -添加到包装的高亮文本中，默认是tt-highlight。

覆盖这些默认值，你可使用classNames选项。

$('.typeahead').typeahead({
  classNames: {
    input: 'Typeahead-input',
    hint: 'Typeahead-hint',
    selectable: 'Typeahead-selectable'
  }
});