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：可用于本地數(shù)據(jù)的一個數(shù)組。支持兩種格式：
  • 字符串數(shù)組：[ "Choice1", "Choice2" ]
  • 帶有 label 和 value 屬性的對象數(shù)組：[ { label: "Choice1", value: "value1" }, ... ]
  label 屬性顯示在建議菜單中。當用戶選擇一個條目時，value 將被插入到 input 元素中。如果只是指定了一個屬性，則該屬性將被視為 label 和 value，例如，如果您只提供了 value 屬性，value 也會被視為標簽。
• String：當使用一個字符串，Autocomplete 插件希望該字符串指向一個能返回 JSON 數(shù)據(jù)的 URL 資源。它可以是在相同的主機上，也可以是在不同的主機上（必須提供 JSONP）。Autocomplete 插件不過濾結果，而是通過一個 term 字段添加了一個查詢字符串，用于服務器端腳本過濾結果。例如，如果 source 選項設置為 "http://example.com"，且用戶鍵入了 foo，GET 請求則為 http://example.com?term=foo。數(shù)據(jù)本身的格式可以與前面描述的本地數(shù)據(jù)的格式相同。
• Function：第三個變量，一個回調(diào)函數(shù)，提供最大的靈活性，可用于連接任何數(shù)據(jù)源到 Autocomplete?；卣{(diào)函數(shù)接受兩個參數(shù)：
  • 一個 request 對象，帶有一個 term 屬性，表示當前文本輸入中的值。例如，如果用戶在 city 字段輸入 "new yo"，則 Autocomplete term 等同于 "new yo"。
  • 一個 response 回調(diào)函數(shù)，提供單個參數(shù)：建議給用戶的數(shù)據(jù)。該數(shù)據(jù)應基于被提供的 term 進行過濾，且可以是上面描述的本地數(shù)據(jù)的任何格式。用于在請求期間提供自定義 source 回調(diào)來處理錯誤。即使遇到錯誤，您也必須調(diào)用 response 回調(diào)函數(shù)。這就確保了小部件總是正確的狀態(tài)。

  當過濾本地數(shù)據(jù)時，您可以使用內(nèi)置的 $.ui.autocomplete.escapeRegex 函數(shù)。它會接受一個字符串參數(shù)，轉(zhuǎn)義所有的正則表達式字符，讓結果安全地傳遞到 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" ] );
	

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用 close 方法：

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

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用 destroy 方法：

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

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用 disable 方法：

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

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用 enable 方法：

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

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

代碼實例：

調(diào)用該方法：

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

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用該方法：

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

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

代碼實例：

調(diào)用該方法：

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

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

代碼實例：

調(diào)用該方法：

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

• value
  類型：String

代碼實例：

調(diào)用 search 方法：

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

• 該方法不接受任何參數(shù)。

代碼實例：

調(diào)用 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
  描述：新創(chuàng)建的 <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
  描述：一個數(shù)組，數(shù)組元素為匹配用戶輸入的條目。每個條目是一個帶有 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" );
}
	

• 該方法不接受任何參數(shù)。

代碼實例：

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

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

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

代碼實例：

初始化帶有指定 change 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompletechange 事件：

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

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

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

代碼實例：

初始化帶有指定 close 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompleteclose 事件：

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

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

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

代碼實例：

初始化帶有指定 create 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompletecreate 事件：

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

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

代碼實例：

初始化帶有指定 focus 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompletefocus 事件：

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

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

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

代碼實例：

初始化帶有指定 open 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompleteopen 事件：

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

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

代碼實例：

初始化帶有指定 response 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompleteresponse 事件：

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

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

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

代碼實例：

初始化帶有指定 search 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompletesearch 事件：

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

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

代碼實例：

初始化帶有指定 select 回調(diào)的 autocomplete：

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

綁定一個事件監(jiān)聽器到 autocompleteselect 事件：

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