Latest web development tutorials

jQuery UI API - AutoComplete member (Autocomplete Widget)

category

Widgets (Widgets)

usage

Description: auto-complete search and filter value based on user input, allowing users to quickly find and select from a list of preset values.

New version: 1.8

Any field can receive input can be converted to Autocomplete, namely, <input> element, <textarea> element and with contenteditable element attributes.

By giving Autocomplete focus or field in which you enter characters, the plug began to search for a matching entry and display a list of alternative values. By entering more characters, the user can filter the list to get a better match.

The components can be used to select the previously selected value, such as input or tag Input Address e-mail address from the address book. Autocomplete also be used to fill the relevant information, such as input the name of a city to get the city's ZIP code.

You can get from a local or remote source data source: the local source for small data sets, for example, an address book with 50 entries; remote source for large data sets, for example, with hundreds or thousands database entries. For more information about custom data source, see the source document options.

Keyboard interaction

When the menu is open, the following keyboard commands are available:

  • UP - Move cursor to the previous item. If on the first item, then move the focus to the input (input). If the input (input), the focus will move to the last item.
  • DOWN - to move the focus to the next item. If the last item, then move the focus to the input (input). If the input (input), the focus will move to the first item.
  • ESCAPE - off menu.
  • ENTER - Select the current project has focus, and close the menu.
  • TAB - get to select the current focus of the project, close the menu, and move the focus to the next focusable (focusable) elements.
  • PAGE UP / DOWN - scroll one screen projects (based on the height of the menu).

When the menu is closed, the following keyboard commands are available:

  • UP / DOWN - if they meet minLength , then open the menu.

Theming

AutoComplete member (Autocomplete Widget) using jQuery UI CSS framework to define the look and feel of its style. If you need to use the AutoComplete member designated style, you can use the following CSS class name:

  • ui-autocomplete : to match the user's display menu (menu)
  • ui-autocomplete-input : auto-complete component (Autocomplete Widget) Examples of input elements.

rely

Additional information

  • The part requires some functional CSS, otherwise it will not work. If you create a custom theme, use the widget specified CSS file as a starting point.
  • The components to programmatically manipulate the value of the element, so that when the value of the element changes do not trigger the native change events.

Quick navigation

选项 方法 扩展点 事件

选项 类型 描述 默认值
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 Gonzalez' 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 ) {} );
	

Examples

Example 1:

A simple jQuery UI auto-completion (Autocomplete).

<! Doctype html>
<Html lang = "en">
<Head>
  <Meta charset = "utf-8">
  <Title> AutoComplete member (Autocomplete Widget) Demo </ 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"> select a programming language: </ label>
<Input id = "autocomplete">
 
<Script>
$ ( "#autocomplete") .autocomplete ({
  source: [ "c ++", "java", "php", "coldfusion", "javascript", "asp", "ruby"]
});
</ Script>
 
</ Body>
</ Html>

Example 2:

Start using custom source correction to match the conditions.

<! Doctype html>
<Html lang = "en">
<Head>
  <Meta charset = "utf-8">
  <Title> AutoComplete member (Autocomplete Widget) Demo </ 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"> select a programming language: </ 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>