jQuery UI API - 自动完成部件（Autocomplete Widget） · W3School jQuery UI 教程

# jQuery UI API - 自动完成部件（Autocomplete Widget） ## 所属类别 [小部件（Widgets）](ref-widgets.html) ## 用法 **描述：**自动完成功能根据用户输入值进行搜索和过滤，让用户快速找到并从预设值列表中选择。 **版本新增：**1.8 任何可以接收输入的字段都可以转换为 Autocomplete，即，`<input>` 元素，`<textarea>` 元素及带有 `contenteditable` 属性的元素。通过给 Autocomplete 字段焦点或者在其中输入字符，插件开始搜索匹配的条目并显示供选择的值的列表。通过输入更多的字符，用户可以过滤列表以获得更好的匹配。该部件可用于选择先前选定的值，比如输入文章标签或者输入从地址簿中输入地址邮件地址。Autocomplete 也可以用来填充相关的信息，比如输入一个城市的名称来获得该城市的邮政编码。您可以从本地源或者远程源获取数据：本地源适用于小数据集，例如，带有 50 个条目的地址簿；远程源适用于大数据集，比如，带有数百个或者成千上万个条目的数据库。如需了解更多有关自定义数据源的信息，请查看 [`source`](#option-source) 选项的文档。 ### 键盘交互当菜单打开时，下面的键盘命令可用： * UP - 移动焦点到上一个项目。如果在第一个项目上，则移动焦点到输入（input）。如果在输入（input）上，则移动焦点到最后一个项目。 * DOWN - 移动焦点到下一个项目。如果在最后一个项目上，则移动焦点到输入（input）。如果在输入（input）上，则移动焦点到第一个项目。 * ESCAPE - 关闭菜单。 * ENTER - 选择当前获得焦点的项目，并关闭菜单。 * TAB - 选择当前获得焦点的项目，关闭菜单，并移动焦点到下一个可聚焦（focusable）的元素。 * PAGE UP/DOWN - 滚动一屏的项目（基于菜单的高度）。当菜单关闭时，下面的键盘命令可用： * UP/DOWN - 如果满足 [`minLength`](#option-minLength)，则打开菜单。 ### 主题化自动完成部件（Autocomplete Widget）使用 [jQuery UI CSS 框架](api-css-framework.html) 来定义它的外观和感观的样式。如果需要使用自动完成部件指定的样式，则可以使用下面的 CSS class 名称： * `ui-autocomplete`：用于显示匹配用户的 [菜单（menu）](api-menu.html#theming) * `ui-autocomplete-input`：自动完成部件（Autocomplete Widget）实例化的 input 元素。 ### 依赖 * [UI 核心（UI Core）](ref-ui-core.html) * [部件库（Widget Factory）](api-jQuery-widget.html) * [定位（Position）](api-position.html) * [菜单部件（Menu Widget）](api-menu.html) ### 附加说明 * 该部件要求一些功能性的 CSS，否则将无法工作。如果您创建了一个自定义的主题，请使用小部件指定的 CSS 文件作为起点。 * 该部件以编程方式操作元素的值，因此当元素的值改变时不会触发原生的 `change` 事件。 ### 快速导航 | 选项 | 方法 | 扩展点 | 事件 | | --- | --- | --- | --- | | [appendTo](#option-appendTo)[autoFocus](#option-autoFocus)[delay](#option-delay)[disabled](#option-disabled)[minLength](#option-minLength)[position](#option-position)[source](#option-source) | [close](#method-close)[destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[search](#method-search)[widget](#method-widget) | [_renderItem](#method-_renderItem)[_renderMenu](#method-_renderMenu)[_resizeMenu](#method-_resizeMenu) | [change](#event-change)[close](#event-close)[create](#event-create)[focus](#event-focus)[open](#event-open)[response](#event-response)[search](#event-search)[select](#event-select) | #### appendTo **类型**：Selector **描述**：菜单应该被附加到哪一个元素。当该值为 `null` 时，输入域的父元素将检查 `ui-front` class。如果找到带有 `ui-front` class 的元素，菜单将被附加到该元素。如果未找到带有 `ui-front` class 的元素，不管值为多少，菜单将被附加到 body。 **注意：当建议菜单打开时，`appendTo` 选项不应改变。** **代码实例：** 初始化带有指定 `appendTo` 选项的 autocomplete： ``` $( ".selector" ).autocomplete({ appendTo: "#someElem" }); ``` 在初始化后，获取或设置 `appendTo` 选项： ``` // getter var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" ); // setter $( ".selector" ).autocomplete( "option", "appendTo", "#someElem" ); ``` **默认值**：null #### autoFocus **类型**：Boolean **描述**：如果设置为 `true`，当菜单显示时，第一个条目将自动获得焦点。 **代码实例：** 初始化带有指定 `autoFocus` 选项的 autocomplete： ``` $( ".selector" ).autocomplete({ autoFocus: true }); ``` 在初始化后，获取或设置 `autoFocus` 选项： ``` // getter var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" ); // setter $( ".selector" ).autocomplete( "option", "autoFocus", true ); ``` **默认值**：false #### delay **类型**：Integer **描述**：按键和执行搜索之间的延迟，以毫秒计。对于本地数据，采用零延迟是有意义的（更具响应性），但对于远程数据会产生大量的负荷，同时降低了响应性。 **代码实例：** 初始化带有指定 `delay` 选项的 autocomplete： ``` $( ".selector" ).autocomplete({ delay: 500 }); ``` 在初始化后，获取或设置 `delay` 选项： ``` // getter var delay = $( ".selector" ).autocomplete( "option", "delay" ); // setter $( ".selector" ).autocomplete( "option", "delay", 500 ); ``` **默认值**：300 #### disabled **类型**：Boolean **描述**：如果设置为 `true`，则禁用该 autocomplete。 **代码实例：** 初始化带有指定 `disabled` 选项的 autocomplete： ``` $( ".selector" ).autocomplete({ disabled: true }); ``` 在初始化后，获取或设置 `disabled` 选项： ``` // getter var disabled = $( ".selector" ).autocomplete( "option", "disabled" ); // setter $( ".selector" ).autocomplete( "option", "disabled", true ); ``` **默认值**：false #### minLength **类型**：Integer **描述**：执行搜索前用户必须输入的最小字符数。对于仅带有几项条目的本地数据，通常设置为零，但是当单个字符搜索会匹配几千项条目时，设置个高数值是很有必要的。 **代码实例：** 初始化带有指定 `minLength` 选项的 autocomplete： ``` $( ".selector" ).autocomplete({ minLength: 0 }); ``` 在初始化后，获取或设置 `minLength` 选项： ``` // getter var minLength = $( ".selector" ).autocomplete( "option", "minLength" ); // setter $( ".selector" ).autocomplete( "option", "minLength", 0 ); ``` **默认值**：1 #### position **类型**：Object **描述**：标识建议菜单的位置与相关的 input 元素有关系。`of` 选项默认为 input 元素，但是您可以指定另一个定位元素。如需了解各种选项的更多细节，请查看 [jQuery UI 定位（Position）](api-position.html)。 **代码实例：** 初始化带有指定 `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" } ); ``` **默认值**：{ my: "left top", at: "left bottom", collision: "none" } #### source **类型**：Array 或 String 或 Function( Object request, Function response( Object data ) ) **描述**：定义要使用的数据，必须指定。独立于您要使用的变量，标签总是被视为文本。如果您想要标签被视为 html，您可以使用 [Scott González' html 扩展](https://github.com/scottgonzalez/jquery-ui-extensions/blob/master/src/autocomplete/jquery.ui.autocomplete.html.js)。演示侧重于 `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()`。 **代码实例：** 初始化带有指定 `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" ] ); ``` **默认值**：none; must be specified #### 方法 #### close() **类型**：jQuery (plugin only) **描述**：关闭 Autocomplete 菜单。当与 `[search](#method-search)` 方法结合使用时，可用于关闭打开的菜单。 * 该方法不接受任何参数。 **代码实例：** 调用 close 方法： ``` $( ".selector" ).autocomplete( "close" ); ``` #### destroy() **类型**：jQuery (plugin only) **描述**：完全移除 autocomplete 功能。这会把元素返回到它的预初始化状态。 * 该方法不接受任何参数。 **代码实例：** 调用 destroy 方法： ``` $( ".selector" ).autocomplete( "destroy" ); ``` #### disable() **类型**：jQuery (plugin only) **描述**：禁用 autocomplete。 * 该方法不接受任何参数。 **代码实例：** 调用 disable 方法： ``` $( ".selector" ).autocomplete( "disable" ); ``` #### enable() **类型**：jQuery (plugin only) **描述**：启用 autocomplete。 * 该方法不接受任何参数。 **代码实例：** 调用 enable 方法： ``` $( ".selector" ).autocomplete( "enable" ); ``` #### option( optionName ) **类型**：Object **描述**：获取当前与指定的 `optionName` 关联的值。 * **optionName** 类型：String 描述：要获取的选项的名称。 **代码实例：** 调用该方法： ``` var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" ); ``` #### option() **类型**：PlainObject **描述**：获取一个包含键/值对的对象，键/值对表示当前 autocomplete 选项哈希。 * 该方法不接受任何参数。 **代码实例：** 调用该方法： ``` var options = $( ".selector" ).autocomplete( "option" ); ``` #### option( optionName, value ) **类型**：jQuery (plugin only) **描述**：设置与指定的 `optionName` 关联的 autocomplete 选项的值。 * **optionName** 类型：String 描述：要设置的选项的名称。 * **value** 类型：Object 描述：要为选项设置的值。 **代码实例：** 调用该方法： ``` $( ".selector" ).autocomplete( "option", "disabled", true ); ``` #### option( options ) **类型**：jQuery (plugin only) **描述**：为 autocomplete 设置一个或多个选项。 * **options** 类型：Object 描述：要设置的 option-value 对。 **代码实例：** 调用该方法： ``` $( ".selector" ).autocomplete( "option", { disabled: true } ); ``` #### search( [value ] ) **类型**：jQuery (plugin only) **描述**：触发 [`search`](#event-search) 事件，如果该事件未被取消则调用数据源。当被点击时，可被类似选择框按钮用来打开建议。当不带参数调用该方法时，则使用当前输入的值。可带一个空字符串和 `minLength: 0` 进行调用，来显示所有的条目。 * **value** 类型：String **代码实例：** 调用 search 方法： ``` $( ".selector" ).autocomplete( "search", "" ); ``` #### widget() **类型**：jQuery **描述**：返回一个包含菜单元素的 `jQuery` 对象。虽然菜单项不断地被创建和销毁。菜单元素本身会在初始化时创建，并不断的重复使用。 * 该方法不接受任何参数。 **代码实例：** 调用 widget 方法： ``` $( ".selector" ).autocomplete( "widget" ); ``` 自动完成部件（Autocomplete Widget）通过 [部件库（Widget Factory）](api-jQuery-widget.html) 创建的，且可被扩展。当对部件进行扩展时，您可以重载或者添加扩展部件的行为。下面提供的方法作为扩展点，与上面列出的 [插件方法](#methods) 具有相同的 API 稳定性。如需了解更多有关小部件扩展的知识，请查看 [通过部件库（Widget Factory）扩展小部件](jqueryui-widget-extend.html). #### _renderItem( ul, item ) **类型**：jQuery **描述**：Method that controls the creation of each option in the widget's menu. The method must create a new `<li>` element, append it to the menu, and return it. _Note: At this time the`<ul>` element created must contain an `<a>` element for compatibility with the [menu](/menu/) widget. See the example below._ * **ul** 类型：jQuery 描述：新创建的 `<li>` 元素必须追加到的 `<ul>` 元素。 * **item** 类型：Object * **label** 类型：String 描述：条目显示的字符串。 * **item** 类型：String 描述：当条目被选中时插入到输入框中的值。 **代码实例：** 添加条目的值作为 `<li>` 上的 data 属性。 ``` _renderItem: function( ul, item ) { return $( "<li>" ) .attr( "data-value", item.value ) .append( $( "<a>" ).text( item.label ) ) .appendTo( ul ); } ``` #### _renderMenu( ul, items ) **类型**：jQuery (plugin only) **描述**：该方法负责在菜单显示前调整菜单尺寸。菜单元素可通过 `this.menu.element` 使用。 * **ul** 类型：jQuery 描述：一个要作为小部件的菜单使用的空的 `<ul>` 元素。 * **items** 类型：Array 描述：一个数组，数组元素为匹配用户输入的条目。每个条目是一个带有 `label` 和 `value` 属性的对象。 **代码实例：** 添加一个 CSS class 名称到旧的菜单项。 ``` _renderMenu: function( ul, items ) { var that = this; $.each( items, function( index, item ) { that._renderItemData( ul, item ); }); $( ul ).find( "li:odd" ).addClass( "odd" ); } ``` #### _resizeMenu() **类型**：jQuery (plugin only) **描述**：该方法负责在菜单显示前调整菜单尺寸。菜单元素可通过 `this.menu.element` 使用。 * 该方法不接受任何参数。 **代码实例：** 菜单总是显示为 500 像素宽。 ``` _resizeMenu: function() { this.menu.element.outerWidth( 500 ); } ``` #### 事件 #### change( event, ui ) **类型**：autocompletechange **描述**：如果输入域的值改变则触发该事件。 * **event** 类型：Event * **ui** 类型：Object * **item** 类型：Object 描述：从菜单中选择的条目，否则属性为 `null`。 **代码实例：** 初始化带有指定 change 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ change: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompletechange 事件： ``` $( ".selector" ).on( "autocompletechange", function( event, ui ) {} ); ``` #### close( event, ui ) **类型**：autocompleteclose **描述**：当菜单隐藏时触发。不是每一个 `close` 事件都伴随着 `change` 事件。 * **event** 类型：Event * **ui** 类型：Object 注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。 **代码实例：** 初始化带有指定 close 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ close: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompleteclose 事件： ``` $( ".selector" ).on( "autocompleteclose", function( event, ui ) {} ); ``` #### create( event, ui ) **类型**：autocompletecreate **描述**：当创建 autocomplete 时触发。 * **event** 类型：Event * **ui** 类型：Object 注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。 **代码实例：** 初始化带有指定 create 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ create: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompletecreate 事件： ``` $( ".selector" ).on( "autocompletecreate", function( event, ui ) {} ); ``` #### focus( event, ui ) **类型**：autocompletefocus **描述**：当焦点移动到一个条目上（未选择）时触发。默认的动作是把文本域中的值替换为获得焦点的条目的值，即使该事件是通过键盘交互触发的。取消该事件会阻止值被更新，但不会阻止菜单项获得焦点。 * **event** 类型：Event * **ui** 类型：Object * **item** 类型：Object 描述：获得焦点的条目。 **代码实例：** 初始化带有指定 focus 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ focus: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompletefocus 事件： ``` $( ".selector" ).on( "autocompletefocus", function( event, ui ) {} ); ``` #### open( event, ui ) **类型**：autocompleteopen **描述**：当打开建议菜单或者更新建议菜单时触发。 * **event** 类型：Event * **ui** 类型：Object 注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。 **代码实例：** 初始化带有指定 open 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ open: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompleteopen 事件： ``` $( ".selector" ).on( "autocompleteopen", function( event, ui ) {} ); ``` #### response( event, ui ) **类型**：autocompleteresponse **描述**：在搜索完成后菜单显示前触发。用于建议数据的本地操作，其中自定义的 [`source`](#option-source) 选项回调不是必需的。该事件总是在搜索完成时触发，如果搜索无结果或者禁用了 Autocomplete，导致菜单未显示，该事件一样会被触发。 * **event** 类型：Event * **ui** 类型：Object * **content** 类型：Array 描述：包含响应数据，且可被修改来改变显示结果。该数据已经标准化，所以如果您要修改数据，请确保每个条目都包含 `value` 和 `label` 属性。 **代码实例：** 初始化带有指定 response 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ response: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompleteresponse 事件： ``` $( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} ); ``` #### search( event, ui ) **类型**：autocompletesearch **描述**：在搜索执行前满足 [`minLength`](#option-minLength) 和 [`delay`](#option-delay) 后触发。如果取消该事件，则不会提交请求，也不会提供建议条目。 * **event** 类型：Event * **ui** 类型：Object 注意：`ui` 对象是空的，这里包含它是为了与其他事件保持一致性。 **代码实例：** 初始化带有指定 search 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ search: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompletesearch 事件： ``` $( ".selector" ).on( "autocompletesearch", function( event, ui ) {} ); ``` #### select( event, ui ) **类型**：autocompleteselect **描述**：当从菜单中选择条目时触发。默认的动作是把文本域中的值替换为被选中的条目的值。取消该事件会阻止值被更新，但不会阻止菜单关闭。 * **event** 类型：Event * **ui** 类型：Object * **item** 类型：Object 描述：一个带有被选项的 `label` 和 `value` 属性的对象。 **代码实例：** 初始化带有指定 select 回调的 autocomplete： ``` $( ".selector" ).autocomplete({ select: function( event, ui ) {} }); ``` 绑定一个事件监听器到 autocompleteselect 事件： ``` $( ".selector" ).on( "autocompleteselect", function( event, ui ) {} ); ``` ## 实例 **实例 1：** 一个简单的 jQuery UI 自动完成（Autocomplete）。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>自动完成部件（Autocomplete Widget）演示</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">选择一个编程语言：</label> <input id="autocomplete"> <script> $( "#autocomplete" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] }); </script> </body> </html> ``` **实例 2：** 使用自定义源回调来匹配条件的开始。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>自动完成部件（Autocomplete Widget）演示</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">选择一个编程语言：</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> ```