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 ) {} );