README

Devbridge Group 通过专业产品团队、用户体验和软件工程专长，加速企业客户的软件上市。

www.devbridge.com

jQuery Ajax 自动完成

jQuery Ajax 自动完成允许您轻松为文本输入字段创建自动完成/自动建议框。

除了jQuery没有其他依赖。

标准jquery.autocomplete.js文件在压缩后约为13KB。

API

$(selector).autocomplete(options);
- 为输入字段设置自动完成。
- options: 一个对象字面量，用于定义自动完成插件要使用的设置。以下列出了可用的选项设置。

Ajax设置

serviceUrl: 服务器端URL或返回serviceUrl字符串的回调函数。如果提供了本地查找数据，则为可选。
type: 用于获取建议的Ajax请求类型。默认：GET。
dataType: 从服务器返回的数据类型。可以是text（默认）、json或jsonp，这将使自动完成使用jsonp。当使用jsonp时，您可以在回调中使用json对象返回。
paramName: 默认query。包含查询的请求参数的名称。
params: 要与请求一起传递的附加参数，可选。
deferRequestBy: 延迟Ajax请求的毫秒数。默认：0。
ajaxSettings: 配置jQuery Ajax请求的任何其他Ajax设置。

配置设置

noCache: 表示是否缓存建议结果的布尔值。默认：false。
delimiter: 字符串或正则表达式，用于分割输入值并将最后一部分用作查询的建议。当例如需要填充由逗号分隔的值列表时很有用。
onSearchStart: 在Ajax请求之前调用的function (params) {}。this绑定到输入元素。
onSearchComplete: 在处理完Ajax响应后调用的function (query, suggestions) {}。this绑定到输入元素。suggestions是一个包含结果的数组。
onSearchError: 如果Ajax请求失败，则调用function (query, jqXHR, textStatus, errorThrown) {}。this绑定到输入元素。
transformResult: 在查询结果准备就绪后调用的function(response, originalQuery) {}。将结果转换为response.suggestions格式。
onSelect: 当用户从列表中选择建议时调用的回调函数function (suggestion) {}。回调中的this指的是输入HtmlElement。
minChars: 触发自动建议所需的最小字符数。默认：1。
lookupLimit: 要显示的本地查找的最大结果数。默认：无限制。
lookup: 建议的回调函数或查找数组。它可以是字符串数组或suggestion对象字面量。
- suggestion: 一个对象字面量，其格式如下：{ value: 'string', data: any }。
lookupFilter: function (suggestion, query, queryLowerCase) {} 用于本地查找的过滤器函数。默认执行部分字符串匹配（不区分大小写）。
triggerSelectOnValidInput：布尔值，表示是否在匹配建议时触发 select。默认 true。
preventBadQueries：布尔值，表示是否防止返回空结果的查询再次发起 Ajax 请求。例如，如果 Jam 返回无建议，则不会为任何以 Jam 开头的后续查询触发。默认 true。
autoSelectFirst：如果设置为 true，则在显示建议时将选择第一个项。默认值 false。
onHide：在容器隐藏前调用的 function (container) {}。

展示设置

beforeRender：在显示建议前调用的 function (container, suggestions) {}。您可以在建议显示之前操作建议的 DOM。
formatResult：自定义函数 function (suggestion, currentValue) {}，用于格式化建议容器内的建议条目，可选。
formatGroup：自定义函数 function (suggestion, category) {}，用于格式化分组标题，可选。
groupBy：建议 data 对象的属性名，按该属性名对结果进行分组。
maxHeight：建议容器最大高度（像素）。默认：300。
width：建议容器宽度（像素），例如：300，flex 为最大建议大小，auto 为输入字段宽度。默认：auto。
zIndex：建议容器的 'z-index'。默认：9999。
appendTo：建议将附加到的容器。默认值 document.body。可以是 jQuery 对象、选择器或 HTML 元素。确保为此元素设置 position: absolute 或 position: relative。
forceFixPosition：默认：false。当建议容器附加到 body 时，建议将自动定位（查看 appendTo 选项），在其他情况下，建议将被渲染但不会应用定位。将此选项设置为在其他情况下强制自动定位。
orientation：默认 bottom。显示建议的垂直方向，可用值是 auto、top、bottom。如果设置为 auto，则建议将按照使它们靠近视口中间的方式定位。
preserveInput：如果 true，则在浏览建议时输入值保持不变。默认：false。
showNoSuggestionNotice：默认 false。当没有匹配的结果时，显示通知标签。
noSuggestionNotice：默认 No results。无匹配结果标签的文本或 htmlString 或 Element 或 jQuery 对象。
onInvalidateSelection：在输入变更后、选择已做出时调用的 function () {}。`this` 绑定到输入元素。
tabDisabled：默认 false。设置为 true 以在用户使用 Tab 键选择建议后保留光标在输入字段中。

默认选项

所有实例的默认选项可以通过 $.Autocomplete.defaults 访问。

实例方法

Autocomplete 实例有以下方法

setOptions(options)：您可以随时更新任何选项。选项在上文列出。
clear：清除建议缓存和当前建议。
clearCache：清除建议缓存。
disable：停用自动完成。
enable：如果之前已停用，则激活自动完成。
hide：隐藏建议。
dispose：销毁自动完成实例。所有事件都取消绑定，并移除建议容器。

您可以通过两种方式调用 Autocomplete 方法。一种是在 jQuery 对象上调用 autocomplete，并传递方法名作为字符串字面量。如果方法有参数，参数作为连续参数传递。

$('#autocomplete').autocomplete('disable');
$('#autocomplete').autocomplete('setOptions', options);

或者，您可以通过在 jQuery 对象上调用 autcomplete（不带任何参数）来获取 Autocomplete 实例，然后调用所需的方法。

$('#autocomplete').autocomplete().disable();
$('#autocomplete').autocomplete().setOptions(options);

用法

Html

<input type="text" name="country" id="autocomplete"/>

Ajax 查询

$('#autocomplete').autocomplete({
    serviceUrl: '/autocomplete/countries',
    onSelect: function (suggestion) {
        alert('You selected: ' + suggestion.value + ', ' + suggestion.data);
    }
});

本地查询（无 Ajax）

var countries = [
    { value: 'Andorra', data: 'AD' },
    // ...
    { value: 'Zimbabwe', data: 'ZZ' }
];

$('#autocomplete').autocomplete({
    lookup: countries,
    onSelect: function (suggestion) {
        alert('You selected: ' + suggestion.value + ', ' + suggestion.data);
    }
});

自定义查询函数

$('#autocomplete').autocomplete({
    lookup: function (query, done) {
        // Do Ajax call or lookup locally, when done,
        // call the callback and pass your results:
        var result = {
            suggestions: [
                { "value": "United Arab Emirates", "data": "AE" },
                { "value": "United Kingdom",       "data": "UK" },
                { "value": "United States",        "data": "US" }
            ]
        };

        done(result);
    },
    onSelect: function (suggestion) {
        alert('You selected: ' + suggestion.value + ', ' + suggestion.data);
    }
});

样式

以下显示建议的生成 HTML 标记。您可以按任何方式对其进行样式设置。

<div class="autocomplete-suggestions">
    <div class="autocomplete-group"><strong>NHL</strong></div>
    <div class="autocomplete-suggestion autocomplete-selected">...</div>
    <div class="autocomplete-suggestion">...</div>
    <div class="autocomplete-suggestion">...</div>
</div>

样式示例

.autocomplete-suggestions { border: 1px solid #999; background: #FFF; overflow: auto; }
.autocomplete-suggestion { padding: 2px 5px; white-space: nowrap; overflow: hidden; }
.autocomplete-selected { background: #F0F0F0; }
.autocomplete-suggestions strong { font-weight: normal; color: #3399FF; }
.autocomplete-group { padding: 2px 5px; }
.autocomplete-group strong { display: block; border-bottom: 1px solid #000; }

响应格式

服务器的响应必须是遵循JavaScript对象的JSON格式

{
    // Query is not required as of version 1.2.5
    "query": "Unit",
    "suggestions": [
        { "value": "United Arab Emirates", "data": "AE" },
        { "value": "United Kingdom",       "data": "UK" },
        { "value": "United States",        "data": "US" }
    ]
}

数据可以是任何值或对象。数据对象传递给formatResults函数和onSelect回调。如果没有数据，可以仅提供一个字符串数组作为建议

{
    "query": "Unit",
    "suggestions": ["United Arab Emirates", "United Kingdom", "United States"]
}

非标准查询/结果

如果你的Ajax服务期望以不同的格式接收查询，并且以不同于标准响应的格式返回数据，你可以提供“paramName”和“transformResult”选项

$('#autocomplete').autocomplete({
    paramName: 'searchString',
    transformResult: function(response) {
        return {
            suggestions: $.map(response.myData, function(dataItem) {
                return { value: dataItem.valueField, data: dataItem.dataField };
            })
        };
    }
})

结果分组

如果希望结果按组显示，请指定数据属性的groupBy选项。例如，如果你的建议数据格式为

[
    { value: 'Chicago Blackhawks', data: { category: 'NHL' } },
    { value: 'Chicago Bulls', data: { category: 'NBA' } }
]

结果将被格式化为两个组 NHL 和 NBA。

已知问题

如果你与jQuery UI库一起使用它，它还有一个名为autocomplete的插件。在这种情况下，你可以使用插件别名devbridgeAutocomplete

$('.autocomplete').devbridgeAutocomplete({ ... });

似乎对于移动Safari，只有当被点击的对象的CSS将光标设置为pointer时，才会触发点击事件

.autocomplete-suggestion { 
    cursor: pointer;
}

参见问题 #542

许可证

Ajax Autocomplete for jQuery在MIT风格的许可证下免费分发。

作者

托马斯·基德拉 / @tkirda

drakon5999 / jquery-autocomplete

维护者

详细信息