jQuery UI API - 自动完成部件(Autocomplete Widget)

所属类别

小部件(Widgets)

用法

描述:自动完成功能根据用户输入值进行搜索和过滤,让用户快速找到并从预设值列表中选择。

版本新增:1.8

任何可以接收输入的字段都可以转换为 Autocomplete,即,<input> 元素,<textarea> 元素及带有 contenteditable 属性的元素。

通过给 Autocomplete 字段焦点或者在其中输入字符,插件开始搜索匹配的条目并显示供选择的值的列表。通过输入更多的字符,用户可以过滤列表以获得更好的匹配。

该部件可用于选择先前选定的值,比如输入文章标签或者输入从地址簿中输入地址邮件地址。Autocomplete 也可以用来填充相关的信息,比如输入一个城市的名称来获得该城市的邮政编码。

您可以从本地源或者远程源获取数据:本地源适用于小数据集,例如,带有 50 个条目的地址簿;远程源适用于大数据集,比如,带有数百个或者成千上万个条目的数据库。如需了解更多有关自定义数据源的信息,请查看 source 选项的文档。

键盘交互

当菜单打开时,下面的键盘命令可用:

  • UP - 移动焦点到上一个项目。如果在第一个项目上,则移动焦点到输入(input)。如果在输入(input)上,则移动焦点到最后一个项目。
  • DOWN - 移动焦点到下一个项目。如果在最后一个项目上,则移动焦点到输入(input)。如果在输入(input)上,则移动焦点到第一个项目。
  • ESCAPE - 关闭菜单。
  • ENTER - 选择当前获得焦点的项目,并关闭菜单。
  • TAB - 选择当前获得焦点的项目,关闭菜单,并移动焦点到下一个可聚焦(focusable)的元素。
  • PAGE UP/DOWN - 滚动一屏的项目(基于菜单的高度)。

当菜单关闭时,下面的键盘命令可用:

  • UP/DOWN - 如果满足 minLength,则打开菜单。

主题化

自动完成部件(Autocomplete Widget)使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用自动完成部件指定的样式,则可以使用下面的 CSS class 名称:

  • ui-autocomplete:用于显示匹配用户的 菜单(menu)
  • ui-autocomplete-input:自动完成部件(Autocomplete Widget)实例化的 input 元素。

依赖

附加说明

  • 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。
  • 该部件以编程方式操作元素的值,因此当元素的值改变时不会触发原生的 change 事件。

快速导航

选项 方法 扩展点 事件

选项 类型 描述 默认值
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)

代码实例:

初始化带有指定 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 扩展。演示侧重于 source 选项的不同变量 - 您可以查找其中匹配您的使用情况的那个,并查看相关代码。

支持多个类型:

  • Array:可用于本地数据的一个数组。支持两种格式:
    • 字符串数组:[ "Choice1", "Choice2" ]
    • 带有 labelvalue 属性的对象数组:[ { 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 方法结合使用时,可用于关闭打开的菜单。
  • 该方法不接受任何参数。

代码实例:

调用 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 } );
    
widget() jQuery 返回一个包含菜单元素的 jQuery 对象。虽然菜单项不断地被创建和销毁。菜单元素本身会在初始化时创建,并不断的重复使用。
  • 该方法不接受任何参数。

代码实例:

调用 widget 方法:

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

扩展点 返回 描述
自动完成部件(Autocomplete Widget)通过 部件库(Widget Factory) 创建的,且可被扩展。当对部件进行扩展时,您可以重载或者添加扩展部件的行为。下面提供的方法作为扩展点,与上面列出的 插件方法 具有相同的 API 稳定性。如需了解更多有关小部件扩展的知识,请查看 通过部件库(Widget Factory)扩展小部件.
_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 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
    描述:一个数组,数组元素为匹配用户输入的条目。每个条目是一个带有 labelvalue 属性的对象。

代码实例:

添加一个 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 选项回调不是必需的。该事件总是在搜索完成时触发,如果搜索无结果或者禁用了 Autocomplete,导致菜单未显示,该事件一样会被触发。
  • event
    类型:Event
  • ui
    类型:Object
    • content
      类型:Array
      描述:包含响应数据,且可被修改来改变显示结果。该数据已经标准化,所以如果您要修改数据,请确保每个条目都包含 valuelabel 属性。

代码实例:

初始化带有指定 response 回调的 autocomplete:

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

绑定一个事件监听器到 autocompleteresponse 事件:

$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
    
select( event, ui ) autocompleteselect 当从菜单中选择条目时触发。默认的动作是把文本域中的值替换为被选中的条目的值。取消该事件会阻止值被更新,但不会阻止菜单关闭。
  • event
    类型:Event
  • ui
    类型:Object
    • item
      类型:Object
      描述:一个带有被选项的 labelvalue 属性的对象。

代码实例:

初始化带有指定 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>