README

#jQuery Ajax 自动完成插件

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

除了jQuery没有其他依赖。

标准 jquery.autocomplete.js 文件在通过 Closure Compiler 最小化并通过gzip压缩后约为2.7KB。

##API

$(selector).autocomplete(options);
- 为输入字段设置自动完成。
- options: 一个对象字面量，定义了自动完成插件要使用的设置。
  - serviceUrl: 服务器端URL或返回serviceUrl字符串的回调函数。如果提供了本地查找数据，则为可选。
  - lookup: 用于建议的查找数组。它可以是字符串数组或suggestion对象字面量。
    - suggestion: 一个对象字面量，其格式如下：{ value: 'string', data: any }。
  - lookupFilter: function (suggestion, query, queryLowerCase) {} 用于本地查找的过滤器函数。默认情况下，它执行部分字符串匹配（不区分大小写）。
  - lookupLimit: 本地查找显示的最大结果数。默认：无限制。
  - onSelect: function (suggestion) {} 当用户从列表中选择建议时调用的回调函数。回调函数内的this指向输入HtmlElement。
  - minChars: 触发自动建议所需的最小字符数。默认：1。
  - maxHeight: 建议容器最大高度（像素）。默认：300。
  - deferRequestBy: 延迟ajax请求的毫秒数。默认：0。
  - width: 建议容器宽度（像素），例如：300。默认：auto，取输入字段宽度。
  - params: 要与请求一起传递的附加参数，可选。
  - formatResult: function (suggestion, currentValue) {} 自定义函数，用于格式化建议容器内的建议条目，可选。
  - delimiter: 字符串或正则表达式，用于分割输入值并取最后一部分作为建议的查询。当例如需要填充以逗号分隔的值列表时很有用。
  - zIndex: 建议容器的'z-index'。默认：9999。
  - type: 获取建议的Ajax请求类型。默认：GET。
  - noCache: 表示是否缓存建议结果的布尔值。默认 false。
  - onSearchStart: function (query) {} 在ajax请求之前调用。此处的this绑定到输入元素。
  - onSearchComplete: function (query) {} 在处理ajax响应后调用。此处的this绑定到输入元素。
  - onSearchError: function (query, jqXHR, textStatus, errorThrown) {} 如果ajax请求失败则调用。此处的this绑定到输入元素。
  - onInvalidateSelection: function () {} 在选择后更改输入时调用。此处的this绑定到输入元素。
  - triggerSelectOnValidInput: 表示是否在匹配建议时触发select的布尔值。默认 true。
  - beforeRender: function (container) {} 在显示建议之前调用。您可以在显示之前操作建议的DOM。
  - tabDisabled: 默认 false。设置为 true 以在用户使用Tab键选择建议后将光标留在输入字段中。
  - paramName: 默认 query。包含查询的请求参数的名称。
  - transformResult：在查询结果准备就绪后调用 function(response, originalQuery) {}。将结果转换为 response.suggestions 格式。
  - autoSelectFirst：如果设置为 true，则显示建议时将选择第一个项目。默认值 false。
  - appendTo：建议将附加到的容器。默认值 body。可以是 jQuery 对象、选择器或 HTML 元素。请确保为该元素设置 position: absolute 或 position: relative。
  - dataType：从服务器返回的数据类型。可以是 'text'（默认）或 'jsonp'，这将导致自动完成使用 jsonp。使用 jsonp 时，您可以在回调中返回一个 json 对象。

自动完成实例具有以下方法

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

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

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

或者，您可以通过在不传递任何参数的情况下在 jQuery 对象上调用 autcomplete 来获取自动完成实例，然后调用所需的方法。

$('#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);
    }
});

##样式

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

<div class="autocomplete-suggestions">
    <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; }

##响应格式

服务器响应必须是遵循 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 };
            })
        };
    }
})

##许可证

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

##作者

Tomas Kirda / @tkirda

filsh / jquery-autocomplete

维护者

详细信息

README

非标准查询/结果