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> ```