README

Devbridge Group 通过专业产品团队、用户体验和软件工程专业知识，为商业客户提供软件上市加速服务。

www.devbridge.com

jQuery Ajax 自动完成

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

除了jQuery之外没有其他依赖项。

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

API

以下设置了用于自动完成的输入字段，其中 options 是一个对象字面量，用于定义自动完成插件要使用的设置。所有可用的选项设置如下表所示。

$(selector).autocomplete(options);

通用设置（本地和Ajax）

事件函数设置（本地和Ajax）

仅本地设置

仅Ajax设置

默认选项

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

实例方法

自动完成实例有以下方法

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

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

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

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

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

许可证

jQuery Ajax 自动完成组件可以在 MIT 风格的许可证下自由分发。

作者

托马什·基尔达 / @tkirda

mobilefuse / jquery-autocomplete

维护者

详细信息