Autocomplete Widget
Categories: Widgets
version added: 1.8
Description: 自动完成功能根据用户输入值进行搜索和过滤，让用户快速找到并从预设值列表中选择。
QuickNavExamples
Options
Methods
Extension Points
Events
任何可以接收输入的字段都可以转换为 Autocomplete，即，<input> 元素，<textarea> 元素及带有 contenteditable 属性的元素。
通过给 Autocomplete 字段焦点或者在其中输入字符，插件开始搜索匹配的条目并显示供选择的值的列表。通过输入更多的字符，用户可以过滤列表以获得更好的匹配。
该部件可用于选择先前选定的值，比如输入文章标签或者输入从地址簿中输入地址邮件地址。Autocomplete 也可以用来填充相关的信息，比如输入一个城市的名称来获得该城市的邮政编码。
您可以从本地源或者远程源获取数据：本地源适用于小数据集，例如，带有 50 个条目的地址簿；远程源适用于大数据集，比如，带有数百个或者成千上万个条目的数据库。如需了解更多有关自定义数据源的信息，请查看 source 选项的文档。
键盘交互(Keyboard interaction)
当菜单打开时，下面的键盘命令可用：
- UP - 移动焦点到上一个项目。如果在第一个项目上，则移动焦点到输入（input）。如果在输入（input）上，则移动焦点到最后一个项目。
- DOWN - 移动焦点到下一个项目。如果在最后一个项目上，则移动焦点到输入（input）。如果在输入（input）上，则移动焦点到第一个项目。
- ESCAPE - 关闭菜单。
- ENTER - 选择当前获得焦点的项目，并关闭菜单。
- TAB - 选择当前获得焦点的项目，关闭菜单，并移动焦点到下一个可聚焦（focusable）的元素。
- PAGE UP/DOWN - 滚动一屏的项目（基于菜单的高度）。
当菜单关闭时，下面的键盘命令可用：
- UP/DOWN - 如果满足
minLength，则打开菜单。
主题(Theming)
自动完成部件（Autocomplete Widget）使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用自动完成部件指定的样式，则可以使用下面的 CSS class 名称：
ui-autocomplete：用于显示匹配用户的 菜单（menu）ui-autocomplete-input：自动完成部件（Autocomplete Widget）实例化的 input 元素。
依赖(Dependencies)
- UI 核心（UI Core）
- 部件库（Widget Factory）
- 定位（Position）
- 菜单部件（Menu Widget）
其他注意事项:
- 该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。
- 该部件以编程方式操作元素的值，因此当元素的值改变时不会触发原生的
change事件。
选项
appendToType: Selector
Default: null
菜单应该被附加到哪一个元素。当该值为 null 时，输入域的父元素将检查 ui-front class。如果找到带有 ui-front class 的元素，菜单将被附加到该元素。如果未找到带有 ui-front class 的元素，不管值为多少，菜单将被附加到 body。
注意: 当建议菜单打开时，appendTo 选项不应改变。Code examples:
初始化带有指定 appendTo 选项的 autocomplete：
$( ".selector" ).autocomplete({ appendTo: "#someElem" });
在初始化后，获取或设置 appendTo 选项：
// getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
// setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
autoFocusType: Boolean
Default: false如果设置为 true，当菜单显示时，第一个条目将自动获得焦点。Code examples:
初始化带有指定 autoFocus 选项的 autocomplete：
$( ".selector" ).autocomplete({ autoFocus: true });
在初始化后，获取或设置 autoFocus 选项：
// getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
// setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );
delayType: Integer
Default: 300按键和执行搜索之间的延迟，以毫秒计。对于本地数据，采用零延迟是有意义的（更具响应性），但对于远程数据会产生大量的负荷，同时降低了响应性。Code examples:
初始化带有指定 delay 选项的 autocomplete：
$( ".selector" ).autocomplete({ delay: 500 });
在初始化后，获取或设置 delay 选项：
// getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );
// setter
$( ".selector" ).autocomplete( "option", "delay", 500 );
disabledType: Boolean
Default: false如果设置为 true，则禁用该 autocomplete。Code examples:
初始化带有指定 disabled 选项的 autocomplete：
$( ".selector" ).autocomplete({ disabled: true });
在初始化后，获取或设置 disabled 选项：
// getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
// setter
$( ".selector" ).autocomplete( "option", "disabled", true );
minLengthType: Integer
Default: 1执行搜索前用户必须输入的最小字符数。对于仅带有几项条目的本地数据，通常设置为零，但是当单个字符搜索会匹配几千项条目时，设置个高数值是很有必要的。Code examples:
初始化带有指定 minLength 选项的 autocomplete：
$( ".selector" ).autocomplete({ minLength: 0 });
在初始化后，获取或设置 minLength 选项：
// getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
// setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );
positionType: Object
Default: { my: "left top", at: "left bottom", collision: "none" }标识建议菜单的位置与相关的 input 元素有关系。of 选项默认为 input 元素，但是您可以指定另一个定位元素。如需了解各种选项的更多细节，请查看 jQuery UI Position。Code examples:
初始化带有指定 position 选项的 autocomplete：
$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
在初始化后，获取或设置 position 选项：
// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
sourceType: Array or String or Function( Object request, Function response( Object data ) )
Default: none; 必须指定定义要使用的数据，必须指定。
独立于您要使用的变量，标签总是被视为文本。如果您想要标签被视为 html，您可以使用 Scott González' html 扩展 。演示侧重于 source 选项的不同变量 - 您可以查找其中匹配您的使用情况的那个，并查看相关代码。
支持多个类型：
- Array：可用于本地数据的一个数组。支持两种格式：
- 字符串数组：
[ "Choice1", "Choice2" ] - 带有
label和value属性的对象数组：[ { label: "Choice1", value: "value1" }, ... ]label 属性显示在建议菜单中。当用户选择一个条目时，value 将被插入到 input 元素中。如果只是指定了一个属性，则该属性将被视为 label 和 value，例如，如果您只提供了value属性，value 也会被视为标签。
- 字符串数组：
- String：当使用一个字符串，Autocomplete 插件希望该字符串指向一个能返回 JSON 数据的 URL 资源。它可以是在相同的主机上，也可以是在不同的主机上（必须提供 JSONP）。Autocomplete 插件不过滤结果，而是通过一个
term字段添加了一个查询字符串，用于服务器端脚本过滤结果。例如，如果source选项设置为"http://example.com"，且用户键入了foo，GET 请求则为http://example.com?term=foo。数据本身的格式可以与前面描述的本地数据的格式相同。 Function：第三个变量，一个回调函数，提供最大的灵活性，可用于连接任何数据源到 Autocomplete。回调函数接受两个参数：
- 一个
request对象，带有一个term属性，表示当前文本输入中的值。例如，如果用户在 city 字段输入"new yo"，则 Autocomplete term 等同于"new yo"。 - 一个
response回调函数，提供单个参数：建议给用户的数据。该数据应基于被提供的 term 进行过滤，且可以是上面描述的本地数据的任何格式。用于在请求期间提供自定义 source 回调来处理错误。即使遇到错误，您也必须调用response回调函数。这就确保了小部件总是正确的状态。
当过滤本地数据时，您可以使用内置的
$.ui.autocomplete.escapeRegex函数。它会接受一个字符串参数，转义所有的正则表达式字符，让结果安全地传递到new RegExp()。- 一个
Code examples:
初始化带有指定 source 选项的 autocomplete：
$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
在初始化后，获取或设置 source 选项：
// getter
var source = $( ".selector" ).autocomplete( "option", "source" );
// setter
$( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] );
Methods
close()Returns: jQuery (plugin only)
关闭 Autocomplete 菜单。当与 search 方法结合使用时，可用于关闭打开的菜单。
- 该方法不接受任何参数。
Code examples:
调用 close 方法：
$( ".selector" ).autocomplete( "close" );
destroy()Returns: jQuery (plugin only)
完全移除 autocomplete 功能。这会把元素返回到它的预初始化状态。
- 该方法不接受任何参数。
Code examples:
调用 destroy 方法：
$( ".selector" ).autocomplete( "destroy" );
disable()Returns: jQuery (plugin only)
禁用 autocomplete。
- 该方法不接受任何参数。
Code examples:
调用 disable 方法：
$( ".selector" ).autocomplete( "disable" );
enable()Returns: jQuery (plugin only)
启用 autocomplete。
- 该方法不接受任何参数。
Code examples:
调用 enable 方法：
$( ".selector" ).autocomplete( "enable" );
option( optionName )Returns: Object
获取当前与指定的 optionName 关联的值。
- optionNameType: String要获取值的选项的名称。
Code examples:
调用该方法：
var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
option()Returns: PlainObject
获取一个包含键/值对的对象，键/值对表示当前 autocomplete 选项哈希。
- 该方法不接受任何参数。
Code examples:
调用该方法：
var options = $( ".selector" ).autocomplete( "option" );
option( optionName, value )Returns: jQuery (plugin only)
设置与指定的 optionName 关联的 autocomplete 选项的值。
Code examples:
调用该方法：
$( ".selector" ).autocomplete( "option", "disabled", true );
option( options )Returns: jQuery (plugin only)
为 autocomplete 设置一个或多个选项。
- optionsType: Object要设置的 option-value 对。
Code examples:
调用该方法：
$( ".selector" ).autocomplete( "option", { disabled: true } );
search( [value ] )Returns: jQuery (plugin only)
触发 search 事件，如果该事件未被取消则调用数据源。当被点击时，可被类似选择框按钮用来打开建议。当不带参数调用该方法时，则使用当前输入的值。可带一个空字符串和 minLength: 0 进行调用，来显示所有的条目。
- valueType: String
Code examples:
调用 search 方法：
$( ".selector" ).autocomplete( "search", "" );
widget()Returns: jQuery
返回一个包含菜单元素的 jQuery 对象。虽然菜单项不断地被创建和销毁。菜单元素本身会在初始化时创建，并不断的重复使用。
- 该方法不接受任何参数。
Code examples:
调用 widget 方法：
$( ".selector" ).autocomplete( "widget" );
Extension Points
自动完成部件（Autocomplete Widget）通过 部件库（Widget Factory） 创建的，且可被扩展。当对部件进行扩展时，您可以重载或者添加扩展部件的行为。下面提供的方法作为扩展点，与上面列出的 插件方法 具有相同的 API 稳定性。如需了解更多有关小部件扩展的知识，请查看 通过部件库（Widget Factory）扩展小部件。
_renderItem( ul, item )Returns: jQuery
控制在部件菜单中每个选项的创建的格式化方法 该方法必须创建一个新的<li>元素，追加到菜单中，并返回它。
注意: 为了与menu小部件兼容，这时创建的<ul>元素必须包含一个<a>元素。 请看下面的例子。
Code examples:
添加条目的值作为 <li> 上的 data 属性。
_renderItem: function( ul, item ) {
return $( "<li>" )
.attr( "data-value", item.value )
.append( $( "<a>" ).text( item.label ) )
.appendTo( ul );
}
_renderMenu( ul, items )Returns: jQuery (plugin only)
控制建立部件菜单的方法。该方法传递一个空<ul>和匹配用户输入的术语的项目数组。 创建当个的<li>元素应该委派给_renderItemData()。
- ulType: jQuery一个要作为小部件的菜单使用的空的
<ul>元素。 - itemsType: Array一个数组，数组元素为匹配用户输入的条目。每个条目是一个带有
label和value属性的对象。
Code examples:
添加一个 CSS class 名称到旧的菜单项。
_renderMenu: function( ul, items ) {
var that = this;
$.each( items, function( index, item ) {
that._renderItemData( ul, item );
});
$( ul ).find( "li:odd" ).addClass( "odd" );
}
thod-_resizeMenu">
_resizeMenu()Returns: jQuery (plugin only)
该方法负责在菜单显示前调整菜单尺寸。菜单元素可通过 this.menu.element 使用。
- 该方法不接受任何参数。
Code examples:
菜单总是显示为 500 像素宽。
_resizeMenu: function() {
this.menu.element.outerWidth( 500 );
}
ction id="events">
Events
change( event, ui )Type: autocompletechange
如果输入域的值改变则触发该事件。
Code examples:
初始化带有指定 change 回调的 autocomplete：
$( ".selector" ).autocomplete({
change: function( event, ui ) {}
});
绑定一个事件监听器到 autocompletechange 事件：
$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
close( event, ui )Type: autocompleteclose
当菜单隐藏时触发。不是每一个 close 事件都伴随着 change 事件。
注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 close 回调的 autocomplete：
$( ".selector" ).autocomplete({
close: function( event, ui ) {}
});
绑定一个事件监听器到 autocompleteclose 事件：
$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
create( event, ui )Type: autocompletecreate
当创建 autocomplete 时触发。
注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 create 回调的 autocomplete：
$( ".selector" ).autocomplete({
create: function( event, ui ) {}
});
绑定一个事件监听器到 autocompletecreate 事件：
$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
focus( event, ui )Type: autocompletefocus
当焦点移动到一个条目上（未选择）时触发。默认的动作是把文本域中的值替换为获得焦点的条目的值，即使该事件是通过键盘交互触发的。
取消该事件会阻止值被更新，但不会阻止菜单项获得焦点。
Code examples:
初始化带有指定 focus 回调的 autocomplete：
$( ".selector" ).autocomplete({
focus: function( event, ui ) {}
});
绑定一个事件监听器到 autocompletefocus 事件：
$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
open( event, ui )Type: autocompleteopen
当打开建议菜单或者更新建议菜单时触发。
注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 open 回调的 autocomplete：
$( ".selector" ).autocomplete({
open: function( event, ui ) {}
});
绑定一个事件监听器到 autocompleteopen 事件：
$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
response( event, ui )Type: autocompleteresponse
在搜索完成后菜单显示前触发。用于建议数据的本地操作，其中自定义的 source 选项回调不是必需的。该事件总是在搜索完成时触发，如果搜索无结果或者禁用了 Autocomplete，导致菜单未显示，该事件一样会被触发。
- eventType: Event
- uiType: Object
- contentType: Array包含响应数据，且可被修改来改变显示结果。该数据已经标准化，所以如果您要修改数据，请确保每个条目都包含
value和label属性。
- contentType: Array包含响应数据，且可被修改来改变显示结果。该数据已经标准化，所以如果您要修改数据，请确保每个条目都包含
Code examples:
初始化带有指定 response 回调的 autocomplete：
$( ".selector" ).autocomplete({
response: function( event, ui ) {}
});
绑定一个事件监听器到 autocompleteresponse 事件：
$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
search( event, ui )Type: autocompletesearch
在搜索执行前满足minLength 和 delay 后触发。如果取消该事件，则不会提交请求，也不会提供建议条目。
注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 search 回调的 autocomplete：
$( ".selector" ).autocomplete({
search: function( event, ui ) {}
});
绑定一个事件监听器到 autocompletesearch 事件：
$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
select( event, ui )Type: autocompleteselect
当从菜单中选择条目时触发。默认的动作是把文本域中的值替换为被选中的条目的值。
取消该事件会阻止值被更新，但不会阻止菜单关闭。
- eventType: Event
- uiType: Object
- itemType: ObjectAn Object with
labelandvalueproperties for the selected option.
- itemType: ObjectAn Object with
Code examples:
初始化带有指定 select 回调的 autocomplete：
$( ".selector" ).autocomplete({
select: function( event, ui ) {}
});
绑定一个事件监听器到 autocompleteselect 事件：
$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );
Examples:
Example: 一个简单的 jQuery UI 自动完成（Autocomplete）。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>autocomplete demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">Select a programming language: </label>
<input id="autocomplete">
<script>
$( "#autocomplete" ).autocomplete({
source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ]
});
</script>
</body>
</html>
Example: Using a custom source callback to match only the beginning of terms
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>autocomplete demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">Select a programming language: </label>
<input id="autocomplete">
<script>
var tags = [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ];
$( "#autocomplete" ).autocomplete({
source: function( request, response ) {
var matcher = new RegExp( "^" + $.ui.autocomplete.escapeRegex( request.term ), "i" );
response( $.grep( tags, function( item ){
return matcher.test( item );
}) );
}
});
</script>
</body>
</html>