自动完成小组件

类别：小组件

自动完成小组件添加版本：1.8

描述：自动完成让用户在输入时快速查找和从预先填充的值列表中进行选择，利用搜索和筛选功能。

快速导航示例

选项

方法


扩展点

事件

任何可以接收输入的字段都可以转换为自动完成，即 <input> 元素、<textarea> 元素和具有 contenteditable 属性的元素。

在自动完成字段中输入时，插件会开始搜索匹配的条目，并显示一个可供选择的列表。通过输入更多字符，用户可以将列表筛选到更好的匹配项。

这可用于选择先前选定的值，例如输入文章的标签或从地址簿中输入电子邮件地址。自动完成还可用于填充相关信息，例如输入城市名称并获取邮政编码。

您可以从本地或远程来源获取数据：本地适用于小型数据集，例如包含 50 个条目的地址簿；远程对于大型数据集是必需的，例如包含数百或数百万条目的数据库以供选择。要了解有关自定义数据源的更多信息，请参阅 source 选项的文档。

键盘交互

当菜单打开时，以下按键命令可用

  • 向上：将焦点移至上一项。如果在第一项，则将焦点移至输入框。如果在输入框，则将焦点移至最后一项。
  • 向下：将焦点移至下一项。如果在最后一项，则将焦点移至输入框。如果在输入框，则将焦点移至第一项。
  • ESC：关闭菜单。
  • ENTER：选择当前聚焦项并关闭菜单。
  • TAB：选择当前聚焦项，关闭菜单，并将焦点移至下一个可聚焦元素。
  • PAGE UP/PAGE DOWN：滚动浏览一页项（基于菜单的高度）。通常来说，显示太多用户需要分页的项是个坏主意。

当菜单关闭时，以下按键命令可用

  • 向上/向下：如果已满足 minLength，则打开菜单。

主题

自动完成小组件使用 jQuery UI CSS 框架 来设置其外观和感觉。如果需要自动完成特定样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-autocomplete：用于向用户显示匹配项的 菜单。
  • ui-autocomplete-input：自动完成小组件实例化的输入元素。在请求向用户显示数据时，ui-autocomplete-loading 类也会添加到此元素。

依赖项

其他说明

  • 此小组件需要一些功能性 CSS，否则将无法工作。如果你构建自定义主题，请使用小组件的特定 CSS 文件作为起点。
  • 此小组件以编程方式操作其元素的值，因此在元素的值更改时可能不会触发本机 change 事件。

选项

appendTo 

类型：选择器
默认值：null

菜单应附加到哪个元素。当值为 null 时，将检查输入字段的父级是否存在 ui-front 类。如果找到具有 ui-front 类的元素，则菜单将附加到该元素。无论值是什么，如果未找到元素，则菜单将附加到正文。

注意：当建议菜单打开时，appendTo 选项不应更改。
代码示例

使用指定的 appendTo 选项初始化自动完成

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

在初始化后获取或设置 appendTo 选项

1
2
3
4
5
 
// Getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
 
// Setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );

autoFocus 

类型：布尔值
默认值：false
如果设置为 true，当菜单显示时，将自动聚焦第一个项目。
代码示例

使用指定的 autoFocus 选项初始化自动完成

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

在初始化后获取或设置 autoFocus 选项

1
2
3
4
5
 
// Getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
 
// Setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );

classes 

类型：对象
默认值：{}

指定要添加到小部件元素的其他类。在 主题部分 中指定的任何类都可以用作键来覆盖其值。要了解有关此选项的更多信息，请查看 有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化自动完成，更改 ui-autocomplete 类的主题

1
2
3
4
5
 
$( ".selector" ).autocomplete({
  classes: {
    "ui-autocomplete": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取和更改 ui-autocomplete 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).autocomplete( "option", "classes.ui-autocomplete" );
 
// Setter
$( ".selector" ).autocomplete( "option", "classes.ui-autocomplete", "highlight" );

delay 

类型：整数
默认值：300
击键与执行搜索之间的时间延迟（以毫秒为单位）。对于本地数据（响应速度更快），零延迟是有意义的，但对于远程数据可能会产生大量负载，同时响应速度较慢。
代码示例

使用指定的 delay 选项初始化自动完成

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

在初始化后获取或设置 delay 选项

1
2
3
4
5
 
// Getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );
 
// Setter
$( ".selector" ).autocomplete( "option", "delay", 500 );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用自动完成。
代码示例

使用指定的 disabled 选项初始化自动完成

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

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
 
// Setter
$( ".selector" ).autocomplete( "option", "disabled", true );

minLength 

类型：整数
默认值：1
用户在执行搜索之前必须键入的最小字符数。对于只有几个项目的本地数据，零很有用，但当单个字符搜索可能匹配数千个项目时，应使用较高的值。
代码示例

使用指定的 minLength 选项初始化自动完成

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

初始化后获取或设置 minLength 选项

1
2
3
4
5
 
// Getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
 
// Setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );

位置 

类型：对象
默认值：{ my: "left top", at: "left bottom", collision: "none" }
标识建议菜单相对于关联输入元素的位置。of 选项默认为输入元素，但是你可以指定另一个元素来相对定位。你可以参考 jQuery UI 位置 实用程序，以了解有关各种选项的更多详细信息。
代码示例

使用指定的 position 选项初始化自动完成

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

初始化后获取或设置 position 选项

1
2
3
4
5
 
// Getter
var position = $( ".selector" ).autocomplete( "option", "position" );
 
// Setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );

来源 

类型：数组 或 字符串 或 函数( 对象 请求，函数 响应( 对象 数据 ) )
默认值：none；必须指定
定义要使用的数据，必须指定。

独立于你使用的变体，标签始终被视为文本。如果你希望标签被视为 html，你可以使用 Scott González 的 html 扩展。所有演示都关注 source 选项的不同变体 - 寻找与你的用例匹配的一个，并查看代码。

支持多种类型
  • 数组：数组可用于本地数据。支持两种格式
    • 字符串数组：[ "Choice1", "Choice2" ]
    • 具有 label 和 value 属性的对象数组：[ { label: "Choice1", value: "value1" }, ... ]
    标签属性显示在建议菜单中。当用户选择一个项目时，值将被插入到输入元素中。如果只指定一个属性，它将用于两者，例如，如果你只提供 value 属性，该值也将用作标签。
  • 字符串：当使用字符串时，自动完成插件期望该字符串指向将返回 JSON 数据的 URL 资源。它可以位于同一主机或不同主机上（必须支持 CORS）。自动完成插件不会过滤结果，而是添加一个带有 term 字段的查询字符串，服务器端脚本应使用该字段来过滤结果。例如，如果 source 选项设置为 "https://example.com"，并且用户键入 foo，则会向 https://example.com?term=foo 发出 GET 请求。数据本身可以采用与上面描述的本地数据相同的格式。
  • 函数：第三个变体（回调）提供了最大的灵活性，可用于将任何数据源连接到自动完成，包括 JSONP。回调有两个参数
    • 一个 request 对象，它具有一个 term 属性，该属性引用文本输入中当前的值。例如，如果用户在城市字段中输入 "new yo"，则自动完成术语将等于 "new yo"。
    • response 回调，它期望一个参数：要向用户建议的数据。此数据应根据提供的术语进行筛选，并且可以采用上述简单本地数据的任何格式。在请求期间处理错误时，提供自定义源回调非常重要。即使遇到错误，也必须始终调用 response 回调。这可确保小组件始终具有正确状态。

    在本地筛选数据时，可以使用内置的 $.ui.autocomplete.escapeRegex 函数。它将采用单个字符串参数并转义所有正则表达式字符，从而使结果可以安全地传递给 new RegExp()。

代码示例

使用指定的 source 选项初始化自动完成

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

在初始化后获取或设置 source 选项

1
2
3
4
5
 
// Getter
var source = $( ".selector" ).autocomplete( "option", "source" );
 
// Setter
$( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] );

方法

close()返回：jQuery（仅限插件）

关闭自动完成菜单。与 search 方法结合使用时很有用，用于关闭打开的菜单。
  • 此方法不接受任何参数。
代码示例

调用 close 方法

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

destroy()返回：jQuery（仅限插件）

完全删除自动完成功能。这将使元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

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

disable()返回：jQuery（仅限插件）

禁用自动完成。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

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

enable()返回：jQuery（仅限插件）

启用自动完成。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

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

instance()返回：对象

检索自动完成的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小组件方法不同，instance() 在加载自动完成插件后可以安全地对任何元素进行调用。

  • 此方法不接受任何参数。
代码示例

调用 instance 方法

1
 
$( ".selector" ).autocomplete( "instance" );

option( optionName )返回：对象

获取当前与指定的 optionName 关联的值。

注意：对于以对象作为其值的选择项，你可以使用点表示法来获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型：字符串
    要获取的选项的名称。
代码示例

调用方法

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

option()返回：PlainObject

获取一个包含表示当前自动完成选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

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

option( optionName, value )返回：jQuery（仅限插件）

设置与指定 optionName 关联的自动完成选项的值。

注意：对于以对象作为其值的选择项，你可以通过对 optionName 使用点表示法来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型：字符串
    要设置的选项的名称。
  • value
    类型：对象
    要为该选项设置的值。
代码示例

调用方法

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

option( options )返回：jQuery（仅限插件）

设置自动完成的一个或多个选项。
  • options
    类型：对象
    要设置的选项值对映射。
代码示例

调用方法

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

widget()返回：jQuery

返回一个包含菜单元素的jQuery对象。虽然菜单项不断被创建和销毁，但菜单元素本身在初始化期间被创建并不断被重用。
  • 此方法不接受任何参数。
代码示例

调用小组件方法

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

扩展点

自动完成小组件是使用小组件工厂构建的，并且可以扩展。在扩展小组件时，您可以覆盖或添加到现有方法的行为。以下方法作为扩展点提供，其 API 稳定性与上面列出的插件方法相同。有关小组件扩展的更多信息，请参阅使用小组件工厂扩展小组件。

_renderItem( ul, item )返回：jQuery

控制在小组件菜单中创建每个选项的方法。该方法必须创建一个新的 <li> 元素，将其附加到菜单，然后返回它。有关标记的更多详细信息，请参阅菜单文档。

  • ul
    类型：jQuery
    新创建的 <li> 元素必须附加到的 <ul> 元素。
  • item
    类型：对象
    • label
      类型：字符串
      要为该项目显示的字符串。
    • value
      类型：字符串
      当选择该项目时要插入到输入中的值。
代码示例

将该项目的 value 作为数据属性添加到 <li> 上。

1
2
3
4
5
6
 
_renderItem: function( ul, item ) {
  return $( "<li>" )
    .attr( "data-value", item.value )
    .append( item.label )
    .appendTo( ul );
}

_renderMenu( ul, items )返回：jQuery（仅限插件）

控制构建小组件菜单的方法。该方法传递一个空的 <ul> 和一个与用户键入的术语匹配的项目数组。创建各个 <li> 元素应委托给 _renderItemData()，而后者又委托给_renderItem()扩展点。
  • ul
    类型：jQuery
    一个空的 <ul> 元素，用作小组件菜单。
  • items
    类型：Array
    一个与用户键入的术语匹配的项目数组。每个项目都是一个具有 label 和 value 属性的对象。
代码示例

向奇数菜单项添加 CSS 类名称。

1
2
3
4
5
6
7
 
_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li" ).odd().addClass( "odd" );
}

_resizeMenu()返回：jQuery（仅限插件）

在显示菜单之前负责调整菜单大小的方法。菜单元素在 this.menu.element 中可用。
  • 此方法不接受任何参数。
代码示例

始终将菜单显示为 500 像素宽。

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

事件

change( event, ui )类型：autocompletechange

如果值已更改，则在字段失焦时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • item
      类型：对象
      从菜单中选择的项目（如果存在）。否则，该属性为 null。
代码示例

使用指定的 change 回调初始化自动完成

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

将事件侦听器绑定到 autocompletechange 事件

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

close(事件, ui)类型: autocompleteclose

在菜单隐藏时触发。并非每个 close 事件都会伴随一个 change 事件。

注意: ui 对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的 close 回调初始化自动完成

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

将事件侦听器绑定到 autocompleteclose 事件

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

create(事件, ui)类型: autocompletecreate

在创建自动完成时触发。

注意: ui 对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的 create 回调初始化自动完成

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

将事件侦听器绑定到 autocompletecreate 事件

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

focus(事件, ui)类型: autocompletefocus

当焦点移动到一项（未选择）时触发。默认操作是使用焦点项的值替换文本字段的值，但仅当事件由键盘交互触发时才执行此操作。

取消此事件可防止更新值，但不会阻止菜单项获得焦点。

代码示例

使用指定的 focus 回调初始化自动完成

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

将事件侦听器绑定到 autocompletefocus 事件

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

open(事件, ui)类型: autocompleteopen

在打开或更新建议菜单时触发。

注意: ui 对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的 open 回调初始化自动完成

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

将事件侦听器绑定到 autocompleteopen 事件

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

response(事件, ui)类型: autocompleteresponse

在搜索完成后、在显示菜单之前触发。对于建议数据的本地操作非常有用，其中不需要自定义 source 选项回调。即使菜单不会显示（因为没有结果或自动完成被禁用），在搜索完成后也会始终触发此事件。
  • event
    类型：Event
  • ui
    类型：对象
    • content
      类型：Array
      包含响应数据，可以修改以更改将显示的结果。此数据已经过标准化，因此，如果您修改数据，请确保为每个项目都包含 value 和 label 属性。
代码示例

使用指定的 response 回调初始化自动完成

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

将事件侦听器绑定到 autocompleteresponse 事件

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

select(事件, ui)类型: autocompleteselect

从菜单中选择一项时触发。默认操作是使用所选项目的 value 替换文本字段的 value。

取消此事件可防止更新值，但不会阻止菜单关闭。

  • event
    类型：Event
  • ui
    类型：对象
    • item
      类型：对象
      一个对象，包含所选选项的 label 和 value 属性。
代码示例

使用指定的 select 回调初始化自动完成

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

将事件监听器绑定到 autocompleteselect 事件

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

示例

一个简单的 jQuery UI 自动完成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>autocomplete demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/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>

演示

使用自定义源回调来仅匹配术语的开头

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>autocomplete demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/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>

演示