jQuery UI API – 自動(dòng)完成部件（Autocomplete Widget）

注意：當(dāng)建議菜單打開(kāi)時(shí)，appendTo 選項(xiàng)不應(yīng)改變。

代碼實(shí)例：

初始化帶有指定 appendTo 選項(xiàng)的 autocomplete：

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

在初始化后，獲取或設(shè)置 appendTo 選項(xiàng)：

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

代碼實(shí)例：

初始化帶有指定 autoFocus 選項(xiàng)的 autocomplete：

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

在初始化后，獲取或設(shè)置 autoFocus 選項(xiàng)：

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

代碼實(shí)例：

初始化帶有指定 delay 選項(xiàng)的 autocomplete：

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

在初始化后，獲取或設(shè)置 delay 選項(xiàng)：

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

代碼實(shí)例：

初始化帶有指定 disabled 選項(xiàng)的 autocomplete：

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

在初始化后，獲取或設(shè)置 disabled 選項(xiàng)：

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

代碼實(shí)例：

初始化帶有指定 minLength 選項(xiàng)的 autocomplete：

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

在初始化后，獲取或設(shè)置 minLength 選項(xiàng)：

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

代碼實(shí)例：

初始化帶有指定 position 選項(xiàng)的 autocomplete：

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
	

在初始化后，獲取或設(shè)置 position 選項(xiàng)：

// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
 
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
	

獨(dú)立于您要使用的變量，標(biāo)簽總是被視為文本。如果您想要標(biāo)簽被視為 html，您可以使用 Scott González' html 擴(kuò)展。演示側(cè)重于 source 選項(xiàng)的不同變量 - 您可以查找其中匹配您的使用情況的那個(gè)，并查看相關(guān)代碼。

支持多個(gè)類型：

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

  當(dāng)過(guò)濾本地?cái)?shù)據(jù)時(shí)，您可以使用內(nèi)置的 $.ui.autocomplete.escapeRegex 函數(shù)。它會(huì)接受一個(gè)字符串參數(shù)，轉(zhuǎn)義所有的正則表達(dá)式字符，讓結(jié)果安全地傳遞到 new RegExp()。

代碼實(shí)例：

初始化帶有指定 source 選項(xiàng)的 autocomplete：

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
	

在初始化后，獲取或設(shè)置 source 選項(xiàng)：

// getter
var source = $( ".selector" ).autocomplete( "option", "source" );
 
// setter
$( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] );
	

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

代碼實(shí)例：

調(diào)用 close 方法：

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

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

代碼實(shí)例：

調(diào)用 destroy 方法：

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

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

代碼實(shí)例：

調(diào)用 disable 方法：

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

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

代碼實(shí)例：

調(diào)用 enable 方法：

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

• optionName
  類型：String
  描述：要獲取的選項(xiàng)的名稱。

代碼實(shí)例：

調(diào)用該方法：

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

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

代碼實(shí)例：

調(diào)用該方法：

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

• optionName
  類型：String
  描述：要設(shè)置的選項(xiàng)的名稱。
• value
  類型：Object
  描述：要為選項(xiàng)設(shè)置的值。

代碼實(shí)例：

調(diào)用該方法：

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

• options
  類型：Object
  描述：要設(shè)置的 option-value 對(duì)。

代碼實(shí)例：

調(diào)用該方法：

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

• value
  類型：String

代碼實(shí)例：

調(diào)用 search 方法：

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

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

代碼實(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
    描述：當(dāng)條目被選中時(shí)插入到輸入框中的值。

代碼實(shí)例：

添加條目的值作為 <li> 上的 data 屬性。

_renderItem: function( ul, item ) {
  return $( "<li>" )
    .attr( "data-value", item.value )
    .append( $( "<a>" ).text( item.label ) )
    .appendTo( ul );
}
	

• ul
  類型：jQuery
  描述：一個(gè)要作為小部件的菜單使用的空的 <ul> 元素。
• items
  類型：Array
  描述：一個(gè)數(shù)組，數(shù)組元素為匹配用戶輸入的條目。每個(gè)條目是一個(gè)帶有 label 和 value 屬性的對(duì)象。

代碼實(shí)例：

添加一個(gè) CSS class 名稱到舊的菜單項(xiàng)。

_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li:odd" ).addClass( "odd" );
}
	

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

代碼實(shí)例：

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

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

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

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompletechange 事件：

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

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

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

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompleteclose 事件：

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

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

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

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompletecreate 事件：

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

• event
  類型：Event
• ui
  類型：Object
  • item
    類型：Object
    描述：獲得焦點(diǎn)的條目。

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompletefocus 事件：

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

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

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

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompleteopen 事件：

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

• event
  類型：Event
• ui
  類型：Object
  • content
    類型：Array
    描述：包含響應(yīng)數(shù)據(jù)，且可被修改來(lái)改變顯示結(jié)果。該數(shù)據(jù)已經(jīng)標(biāo)準(zhǔn)化，所以如果您要修改數(shù)據(jù)，請(qǐng)確保每個(gè)條目都包含 value 和 label 屬性。

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompleteresponse 事件：

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

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

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

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompletesearch 事件：

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

• event
  類型：Event
• ui
  類型：Object
  • item
    類型：Object
    描述：一個(gè)帶有被選項(xiàng)的 label 和 value 屬性的對(duì)象。

代碼實(shí)例：

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

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 autocompleteselect 事件：

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