jQuery UI API – 自動完成部件(Autocomplete Widget)
所屬類別
用法
描述:自動完成功能根據用戶輸入值進行搜索和過濾,讓用戶快速找到並從預設值列表中選擇。
版本新增: 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。 注意:当建议菜单打开时, 代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ appendTo: "#someElem" }); 在初始化后,获取或设置 // getter var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" ); // setter $( ".selector" ).autocomplete( "option", "appendTo", "#someElem" ); |
null |
autoFocus | Boolean | 如果设置为 true ,当菜单显示时,第一个条目将自动获得焦点。代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ autoFocus: true }); 在初始化后,获取或设置 // getter var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" ); // setter $( ".selector" ).autocomplete( "option", "autoFocus", true ); |
false |
delay | Integer | 按键和执行搜索之间的延迟,以毫秒计。对于本地数据,采用零延迟是有意义的(更具响应性),但对于远程数据会产生大量的负荷,同时降低了响应性。 代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ delay: 500 }); 在初始化后,获取或设置 // getter var delay = $( ".selector" ).autocomplete( "option", "delay" ); // setter $( ".selector" ).autocomplete( "option", "delay", 500 ); |
300 |
disabled | Boolean | 如果设置为 true ,则禁用该 autocomplete。代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ disabled: true }); 在初始化后,获取或设置 // getter var disabled = $( ".selector" ).autocomplete( "option", "disabled" ); // setter $( ".selector" ).autocomplete( "option", "disabled", true ); |
false |
minLength | Integer | 执行搜索前用户必须输入的最小字符数。对于仅带有几项条目的本地数据,通常设置为零,但是当单个字符搜索会匹配几千项条目时,设置个高数值是很有必要的。 代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ minLength: 0 }); 在初始化后,获取或设置 // getter var minLength = $( ".selector" ).autocomplete( "option", "minLength" ); // setter $( ".selector" ).autocomplete( "option", "minLength", 0 ); |
1 |
position | Object | 标识建议菜单的位置与相关的 input 元素有关系。 of 选项默认为 input 元素,但是您可以指定另一个定位元素。如需了解各种选项的更多细节,请查看 jQuery UI 定位(Position) 。代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } }); 在初始化后,获取或设置 // 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 扩展 。演示侧重于 支持多个类型:
代码实例: 初始化带有指定 $( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] }); 在初始化后,获取或设置 // 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 关联的值。
代码实例: 调用该方法: var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" ); |
option() | PlainObject | 获取一个包含键/值对的对象,键/值对表示当前 autocomplete 选项哈希。
代码实例: 调用该方法: var options = $( ".selector" ).autocomplete( "option" ); |
option( optionName, value ) | jQuery (plugin only) | 设置与指定的 optionName 关联的 autocomplete 选项的值。
代码实例: 调用该方法: $( ".selector" ).autocomplete( "option", "disabled", true ); |
option( options ) | jQuery (plugin only) | 为 autocomplete 设置一个或多个选项。
代码实例: 调用该方法: $( ".selector" ).autocomplete( "option", { disabled: true } ); |
search( [value ] ) | jQuery (plugin only) | 触发 search 事件,如果该事件未被取消则调用数据源。当被点击时,可被类似选择框按钮用来打开建议。当不带参数调用该方法时,则使用当前输入的值。可带一个空字符串和 minLength: 0 进行调用,来显示所有的条目。
代码实例: 调用 search 方法: $( ".selector" ).autocomplete( "search", "" ); |
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
代码实例: 添加条目的值作为 _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 使用。
代码实例: 添加一个 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 | 如果输入域的值改变则触发该事件。
代码实例: 初始化带有指定 change 回调的 autocomplete: $( ".selector" ).autocomplete({ change: function( event, ui ) {} }); 绑定一个事件监听器到 autocompletechange 事件: $( ".selector" ).on( "autocompletechange", function( event, ui ) {} ); |
close( event, ui ) | autocompleteclose | 当菜单隐藏时触发。不是每一个 close 事件都伴随着 change 事件。
注意: 代码实例: 初始化带有指定 close 回调的 autocomplete: $( ".selector" ).autocomplete({ close: function( event, ui ) {} }); 绑定一个事件监听器到 autocompleteclose 事件: $( ".selector" ).on( "autocompleteclose", function( event, ui ) {} ); |
create( event, ui ) | autocompletecreate | 当创建 autocomplete 时触发。
注意: 代码实例: 初始化带有指定 create 回调的 autocomplete: $( ".selector" ).autocomplete({ create: function( event, ui ) {} }); 绑定一个事件监听器到 autocompletecreate 事件: $( ".selector" ).on( "autocompletecreate", function( event, ui ) {} ); |
focus( event, ui ) | autocompletefocus | 当焦点移动到一个条目上(未选择)时触发。默认的动作是把文本域中的值替换为获得焦点的条目的值,即使该事件是通过键盘交互触发的。取消该事件会阻止值被更新,但不会阻止菜单项获得焦点。
代码实例: 初始化带有指定 focus 回调的 autocomplete: $( ".selector" ).autocomplete({ focus: function( event, ui ) {} }); 绑定一个事件监听器到 autocompletefocus 事件: $( ".selector" ).on( "autocompletefocus", function( event, ui ) {} ); |
open( event, ui ) | autocompleteopen | 当打开建议菜单或者更新建议菜单时触发。
注意: 代码实例: 初始化带有指定 open 回调的 autocomplete: $( ".selector" ).autocomplete({ open: function( event, ui ) {} }); 绑定一个事件监听器到 autocompleteopen 事件: $( ".selector" ).on( "autocompleteopen", function( event, ui ) {} ); |
response( event, ui ) | autocompleteresponse | 在搜索完成后菜单显示前触发。用于建议数据的本地操作,其中自定义的 source 选项回调不是必需的。该事件总是在搜索完成时触发,如果搜索无结果或者禁用了 Autocomplete,导致菜单未显示,该事件一样会被触发。
代码实例: 初始化带有指定 response 回调的 autocomplete: $( ".selector" ).autocomplete({ response: function( event, ui ) {} }); 绑定一个事件监听器到 autocompleteresponse 事件: $( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} ); |
search( event, ui ) | autocompletesearch | 在搜索执行前满足 minLength 和 delay 后触发。如果取消该事件,则不会提交请求,也不会提供建议条目。
注意: 代码实例: 初始化带有指定 search 回调的 autocomplete: $( ".selector" ).autocomplete({ search: function( event, ui ) {} }); 绑定一个事件监听器到 autocompletesearch 事件: $( ".selector" ).on( "autocompletesearch", function( event, ui ) {} ); |
select( event, ui ) | autocompleteselect | 当从菜单中选择条目时触发。默认的动作是把文本域中的值替换为被选中的条目的值。取消该事件会阻止值被更新,但不会阻止菜单关闭。
代码实例: 初始化带有指定 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>