jQuery UI API - 自動完成部件（Autocomplete Widget）

注意：當建議菜單打開時，appendTo 選項不應改變。

代碼實例：

初始化帶有指定 appendTo 選項的 autocomplete：

$( ".selector" ).autocomplete({ appendTo: "#someElem" });
    

在初始化後，獲取或設置 appendTo 選項：

// getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );

// setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
    

代碼實例：

初始化帶有指定 autoFocus 選項的 autocomplete：

$( ".selector" ).autocomplete({ autoFocus: true });
    

在初始化後，獲取或設置 autoFocus 選項：

// getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );

// setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );
    

代碼實例：

初始化帶有指定 delay 選項的 autocomplete：

$( ".selector" ).autocomplete({ delay: 500 });
    

在初始化後，獲取或設置 delay 選項：

// getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );

// setter
$( ".selector" ).autocomplete( "option", "delay", 500 );
    

代碼實例：

初始化帶有指定 disabled 選項的 autocomplete：

$( ".selector" ).autocomplete({ disabled: true });
    

在初始化後，獲取或設置 disabled 選項：

// getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );

// setter
$( ".selector" ).autocomplete( "option", "disabled", true );
    

代碼實例：

初始化帶有指定 minLength 選項的 autocomplete：

$( ".selector" ).autocomplete({ minLength: 0 });
    

在初始化後，獲取或設置 minLength 選項：

// getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );

// setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );
    

代碼實例：

初始化帶有指定 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" } );
    

獨立於您要使用的變數，標籤總是被視為文本。如果您想要標籤被視為 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()。

代碼實例：

初始化帶有指定 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" ] );
    

• 該方法不接受任何參數。

代碼實例：

調用 close 方法：

$( ".selector" ).autocomplete( "close" );
    

• 該方法不接受任何參數。

代碼實例：

調用 destroy 方法：

$( ".selector" ).autocomplete( "destroy" );
    

• 該方法不接受任何參數。

代碼實例：

調用 disable 方法：

$( ".selector" ).autocomplete( "disable" );
    

• 該方法不接受任何參數。

代碼實例：

調用 enable 方法：

$( ".selector" ).autocomplete( "enable" );
    

• optionName
  類型：String
  描述：要獲取的選項的名稱。

代碼實例：

調用該方法：

var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
    

• 該方法不接受任何參數。

代碼實例：

調用該方法：

var options = $( ".selector" ).autocomplete( "option" );
    

• optionName
  類型：String
  描述：要設置的選項的名稱。
• value
  類型：Object
  描述：要為選項設置的值。

代碼實例：

調用該方法：

$( ".selector" ).autocomplete( "option", "disabled", true );
    

• options
  類型：Object
  描述：要設置的 option-value 對。

代碼實例：

調用該方法：

$( ".selector" ).autocomplete( "option", { disabled: true } );
    

• value
  類型：String

代碼實例：

調用 search 方法：

$( ".selector" ).autocomplete( "search", "" );
    

• 該方法不接受任何參數。

代碼實例：

調用 widget 方法：

$( ".selector" ).autocomplete( "widget" );
    

Note: At this time the<ul> element created must contain an <a> element for compatibility with the 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 );
}
    

• 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" );
}
    

• 該方法不接受任何參數。

代碼實例：

菜單總是顯示為 500 像素寬。

_resizeMenu: function() {
  this.menu.element.outerWidth( 500 );
}
    

• event
  類型：Event
• ui
  類型：Object
  • item
    類型：Object
    描述：從菜單中選擇的條目，否則屬性為 null。

代碼實例：

初始化帶有指定 change 回調的 autocomplete：

$( ".selector" ).autocomplete({
  change: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompletechange 事件：

$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object

注意：ui 對象是空的，這裏包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 close 回調的 autocomplete：

$( ".selector" ).autocomplete({
  close: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompleteclose 事件：

$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object

注意：ui 對象是空的，這裏包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 create 回調的 autocomplete：

$( ".selector" ).autocomplete({
  create: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompletecreate 事件：

$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object
  • item
    類型：Object
    描述：獲得焦點的條目。

代碼實例：

初始化帶有指定 focus 回調的 autocomplete：

$( ".selector" ).autocomplete({
  focus: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompletefocus 事件：

$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object

注意：ui 對象是空的，這裏包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 open 回調的 autocomplete：

$( ".selector" ).autocomplete({
  open: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompleteopen 事件：

$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object
  • content
    類型：Array
    描述：包含回應數據，且可被修改來改變顯示結果。該數據已經標準化，所以如果您要修改數據，請確保每個條目都包含 value 和 label 屬性。

代碼實例：

初始化帶有指定 response 回調的 autocomplete：

$( ".selector" ).autocomplete({
  response: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompleteresponse 事件：

$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object

注意：ui 對象是空的，這裏包含它是為了與其他事件保持一致性。

代碼實例：

初始化帶有指定 search 回調的 autocomplete：

$( ".selector" ).autocomplete({
  search: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompletesearch 事件：

$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
    

• event
  類型：Event
• ui
  類型：Object
  • item
    類型：Object
    描述：一個帶有被選項的 label 和 value 屬性的對象。

代碼實例：

初始化帶有指定 select 回調的 autocomplete：

$( ".selector" ).autocomplete({
  select: function( event, ui ) {}
});
    

綁定一個事件監聽器到 autocompleteselect 事件：

$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );