jQuery UI AutoComplete 使用说明

jQuery UI AutoComplete 是基于 jQuery UI 的自动完成组件，它能够基于用户输入的字符，从数据源（如本地静态数据源或服务器端动态数据源）中找到匹配的结果并进行展示，同时还支持许多交互和可配置的选项。下面就以实例的方式来详细讲解 jQuery UI AutoComplete 的使用说明。

引入 jQuery UI AutoComplete

jQuery UI AutoComplete 是 jQuery UI 的扩展组件，因此首先需要引入 jQuery 和 jQuery UI 的库文件。可以从官网 https://jqueryui.com/ 下载最新版本的 jQuery 和 jQuery UI，或者使用以下的 CDN 引入：

<!-- 引入 jQuery -->
<script src="https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.min.js"></script>

<!-- 引入 jQuery UI -->
<link rel="stylesheet" href="https://cdn.bootcdn.net/ajax/libs/jqueryui/1.12.1/jquery-ui.min.css">
<script src="https://cdn.bootcdn.net/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script>

初始化

1. 最简单的初始化：

$( "#autocomplete-input" ).autocomplete();

1. 初始化并指定数据源：

$( "#autocomplete-input" ).autocomplete({
  source: [ "Java", "Python", "JavaScript", "C", "C++" ]
});

选项

下面介绍一些 jQuery UI AutoComplete 的核心选项：

source

指定数据源。数据源可以是本地静态数据源，也可以是服务器端动态数据源。本地静态数据源可以是数组，也可以是对象，服务器端动态数据源可以是返回值为数组的 AJAX 请求，也可以是返回值为 Promise 对象的函数/方法。

本地静态数据源

var localData = [ "Java", "Python", "JavaScript", "C", "C++" ];

$( "#autocomplete-input" ).autocomplete({
  source: localData
});

以上的示例中 source 指定了本地静态数据源 localData。在输入框中输入字符时，会自动从数据源中查找与输入字符相关的结果并显示在下拉列表中。

服务器端动态数据源

$( "#autocomplete-input" ).autocomplete({
  source: function( request, response ) {
    $.ajax({
      url: "http://yourserver.com/data",
      data: {
        term: request.term
      },
      success: function( data ) {
        response( data );
      }
    });
  },
  minLength: 2
});

以上示例中 source 指定了服务器端动态数据源，该数据源返回值为 AJAX 请求的结果（即 data 变量）。在这里，我们通过 AJAX GET 请求将用户输入的字符作为参数 term 发送到服务器端（假设数据服务的 URL 为 http://yourserver.com/data），服务器端返回符合条件的结果，jQuery UI AutoComplete 将结果展示在下拉列表中。

minLength

指定用户至少输入多少个字符后才会触发自动完成功能。默认值为 1。

$( "#autocomplete-input" ).autocomplete({
  minLength: 2
});

以上示例中指定了用户至少需要输入 2 个字符才会开始触发自动完成功能。

delay

指定延迟多长时间后触发自动完成功能。默认值为 300 毫秒。

$( "#autocomplete-input" ).autocomplete({
  delay: 500
});

以上示例中指定了延迟 500 毫秒后才会触发自动完成功能。这段时间可以用来等待用户继续输入或修改字符。

autoFocus

指定自动完成选项下拉列表是否应该自动获取焦点。默认值为 false。

$( "#autocomplete-input" ).autocomplete({
  autoFocus: true
});

以上示例中指定选项下拉列表会自动获取焦点。

事件

以下两个事件是 jQuery UI AutoComplete 中最常用的事件：

select

select 事件在用户从自动完成选项下拉列表中选择一项时触发。

$( "#autocomplete-input" ).autocomplete({
  select: function( event, ui ) {
    console.log( "Selected: " + ui.item.value + "，数据源索引：" + ui.item.index );
  }
});

以上的示例中，当用户从列表中选择一个选项时，回调函数会输出所选项的值（即 ui.item.value）和该选项在数据源中的索引（即 ui.item.index）。

response

response 事件在从数据源对象中获取结果后触发，并在数据结果渲染到自动完成下拉列表前进行自定义处理。

$( "#autocomplete-input" ).autocomplete({
  source: function( request, response ) {
    $.ajax({
      url: "http://yourserver.com/data",
      dataType: "json",
      data: {
        term: request.term
      },
      success: function( data ) {

        // 在 response 事件中对数据进行自定义处理
        var formattedData = $.map( data, function( item ) {
          return {
            label: "源：" + item.source + " -> " + "标题：" + item.title,
            value: item.title
          };
        });

        response( formattedData );
      }
    });
  },
  response: function( event, ui ) {
    console.log( "当前获取到数据源：" + ui.content );
  }
});

以上示例中，我们通过 AJAX GET 请求从服务器端获取数据，并通过 response 事件对获取到的数据进行自定义处理，将原数据格式({source: "数据源", title: "标题"})转换为下拉列表的展示格式({label: "源：数据源 -> 标题：标题", value: "标题"})。

示例

示例1：本地静态数据源

<!-- HTML 页面 -->
<input type="text" id="city-input" placeholder="请输入城市名称">

<script>
  $( function() {
    var availableCities = [
      "北京市",
      "上海市",
      "广州市",
      "深圳市",
      "成都市",
      "杭州市",
      "天津市",
      "南京市",
      "重庆市",
      "武汉市"
    ];

    $( "#city-input" ).autocomplete({
      source: availableCities
    });
  });
</script>

以上示例中给出了一个本地静态数据源的使用示例。用户在输入框中输入字符时，会自动从 availableCities 数组中匹配符合条件的结果并显示在下拉列表中。

示例2：服务器端动态数据源

<!-- HTML 页面 -->
<input type="text" id="player-input" placeholder="请输入球员名称">

<script>
  $( function() {
    $( "#player-input" ).autocomplete({
      source: function( request, response ) {
        $.ajax({
          url: "https://www.balldontlie.io/api/v1/players",
          dataType: "json",
          data: {
            search: request.term
          },
          success: function( data ) {
            var formattedData = $.map( data.data, function( item ) {
              return {
                label: "姓名：" + item.first_name + " " + item.last_name + ", 位置：" + item.position + "，球队：" + item.team.full_name,
                value: item.first_name + " " + item.last_name
              };
            });
            response( formattedData );
          }
        });
      },
      minLength: 3,
      delay: 500
    });
  });
</script>

以上示例中给出了一个服务器端动态数据源的使用示例。在这个示例中，我们通过 AJAX GET 请求从 https://www.balldontlie.io 生态的 API 中获取 NBA 球员数据，并将搜索字符作为参数 search 发送到服务器端。在 response 事件中，我们对获取到的数据进行了自定义处理，以便合适地展示在下拉列表中。