jQuery UI 实例 – 自动完成（Autocomplete）（手把手讲解）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言：为什么选择自动完成功能？

在现代 Web 开发中，用户对交互体验的要求越来越高。一个常见的需求是“自动完成”（Autocomplete），即当用户输入文本时，系统能根据已输入内容快速提供匹配建议。这种功能不仅提升操作效率，还能减少输入错误。例如，搜索引擎的搜索框、电商网站的搜索栏，甚至社交媒体的标签选择，都广泛应用了自动完成功能。

jQuery UI 是一套基于 jQuery 的用户界面交互库，它提供了大量开箱即用的组件，其中 Autocomplete 插件就是实现这一功能的利器。相比从零开发，使用 jQuery UI 的 Autocomplete 能让开发者快速实现专业级的交互效果，同时减少代码量和调试时间。本文将通过实例，从基础配置到高级技巧，逐步解析如何掌握这一功能。

基础用法：快速入门自动完成

第一步：引入依赖库

使用 jQuery UI 的 Autocomplete 需要先引入以下两个文件：

1. jQuery 核心库（通常版本在 3.0 以上）
2. jQuery UI 库（需包含 Autocomplete 插件）

<!-- 在 HTML 头部或底部引入 -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>
<link rel="stylesheet" href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">

小贴士：如果项目需要自定义主题，可以替换 themes/base/jquery-ui.css 为其他主题文件。

第二步：初始化 Autocomplete

假设有一个输入框需要添加自动完成功能：

<input type="text" id="search-box" placeholder="输入关键词">

通过以下 JavaScript 代码即可启用 Autocomplete：

$(function() {
  $("#search-box").autocomplete({
    source: ["苹果", "香蕉", "橙子", "葡萄", "草莓"]
  });
});

关键参数解释：

• source：定义建议数据的来源。这里直接传递了一个静态数组，但也可以是函数或远程 URL。
• select：当用户选择某个建议时触发的回调函数，可用于处理后续操作。

比喻：source 就像一个导航系统的“目的地数据库”，Autocomplete 会根据用户输入的字符，在这个数据库中快速筛选匹配项。

进阶功能：灵活控制自动完成行为

1. 动态过滤建议项

静态数组适合简单场景，但实际开发中往往需要根据输入动态筛选数据。可以通过 函数形式的 source 实现：

$("#search-box").autocomplete({
  source: function(request, response) {
    const term = request.term.toLowerCase();
    const allFruits = ["苹果", "香蕉", "橙子", "葡萄", "草莓"];
    const filtered = allFruits.filter(fruit => 
      fruit.toLowerCase().includes(term)
    );
    response(filtered);
  }
});

参数说明：

• request.term：用户当前输入的文本。
• response()：必须调用此函数传递筛选后的结果。

优化建议：当数据量较大时，可考虑使用本地索引（如 Fuse.js）或后端 API 进行分页处理。

2. 自定义建议项的显示样式

默认情况下，建议项以纯文本形式展示。若需添加图标、颜色或 HTML 内容，可通过 _renderItem 方法：

$("#search-box").autocomplete({
  source: ["苹果", "香蕉", "橙子"],
  minLength: 2, // 至少输入 2 个字符才触发建议
  open: function() {
    $(".ui-autocomplete").css("max-height", "200px").scrollable();
  }
}).data("ui-autocomplete")._renderItem = function(ul, item) {
  return $("<li>")
    .append("<div>" + item.value + "</div>")
    .prepend('<img src="fruit-icons/' + item.value + '.png" width="20">')
    .appendTo(ul);
};

关键点：

• minLength：设置触发建议的最小输入长度。
• open：在建议菜单弹出时触发，可用于调整样式或添加滚动条。
• _renderItem：自定义每个建议项的 HTML 结构，需配合 data("ui-autocomplete") 获取插件实例。

3. 连接远程数据源（AJAX）

当数据量庞大或需实时查询时，应从服务器获取数据。例如，搜索用户时：

$("#user-search").autocomplete({
  source: function(request, response) {
    $.ajax({
      url: "/api/users",
      dataType: "json",
      data: {
        term: request.term
      },
      success: function(data) {
        response($.map(data, function(item) {
          return {
            label: item.name,
            value: item.id,
            avatar: item.avatar_url
          };
        }));
      }
    });
  },
  minLength: 2,
  select: function(event, ui) {
    // 处理用户选择后的逻辑
    console.log("选中的用户ID:", ui.item.value);
  }
});

后端接口示例（Node.js + Express）：

app.get("/api/users", (req, res) => {
  const term = req.query.term.toLowerCase();
  const users = [
    { id: 1, name: "张三", avatar_url: "avatar1.jpg" },
    { id: 2, name: "李四", avatar_url: "avatar2.jpg" }
  ];
  const filtered = users.filter(user => 
    user.name.toLowerCase().includes(term)
  );
  res.json(filtered);
});

注意：需确保后端接口返回的字段与前端 source 函数中的 item 结构一致。

4. 事件与回调函数

Autocomplete 提供了多个事件钩子，可用于扩展功能：

实战案例：构建城市搜索功能

场景描述

假设需要一个输入框，允许用户输入城市名称时，从服务器获取匹配结果，并显示城市名称和所属省份。

实现步骤

1. HTML 结构：

<div class="search-container">
  <input type="text" id="city-search" placeholder="输入城市名称">
  <div class="result-message"></div>
</div>

2. CSS 样式：

.ui-autocomplete { max-height: 300px; overflow-y: auto; }
.ui-autocomplete li { padding: 8px 12px; cursor: pointer; }
.ui-autocomplete li:hover { background: #f0f0f0; }
.result-message { margin-top: 10px; color: #666; }

3. JavaScript 逻辑：

$(function() {
  $("#city-search").autocomplete({
    source: function(request, response) {
      $.ajax({
        url: "/api/cities",
        data: { term: request.term },
        success: function(data) {
          response(data.map(city => ({
            label: `${city.name}（${city.province}）`,
            value: city.id,
            province: city.province
          })));
        }
      });
    },
    minLength: 2,
    select: function(event, ui) {
      $(".result-message").text(`您选择了：${ui.item.label}`);
      // 这里可以添加跳转页面或提交表单的代码
    },
    open: function() {
      $(this).removeClass("ui-corner-all").addClass("ui-corner-top");
    },
    close: function() {
      $(this).removeClass("ui-corner-top").addClass("ui-corner-all");
    }
  });
});

4. 后端接口返回示例（JSON 格式）：

[
  {
    "id": 1001,
    "name": "北京市",
    "province": "北京"
  },
  {
    "id": 1002,
    "name": "上海市",
    "province": "上海"
  }
]

功能扩展：添加输入提示

若希望在用户输入过短时显示提示信息，可通过 response 回调实现：

source: function(request, response) {
  const term = request.term;
  if (term.length < 2) {
    response([]);
    $(".result-message").text("至少输入 2 个字符");
  } else {
    // 正常发送请求...
  }
}

常见问题与解决方案

问题 1：自动完成建议不显示

可能原因：

• 未正确引入 jQuery 或 jQuery UI。
• 输入框的 id 或选择器写错。
• source 数据源为空或格式错误。

解决方法：

1. 检查浏览器控制台是否有错误信息。
2. 确认 source 数组或 AJAX 请求返回的数据符合预期。
3. 在简单场景下先使用静态数组测试，再逐步替换为动态数据。

问题 2：性能问题（数据量过大）

当 source 数组包含数千条数据时，过滤操作可能变慢。解决方案包括：

1. 分页加载：仅返回前 10 条匹配项。
2. 后端处理：让服务器端完成复杂过滤。
3. 延迟触发：通过 delay 参数延缓请求触发时间。

$("#search-box").autocomplete({
  delay: 300, // 输入间隔超过 300 毫秒才触发请求
  // 其他配置...
});

问题 3：移动端适配

在移动设备上，建议菜单可能被虚拟键盘遮挡。可通过以下方式优化：

• 调整位置：使用 position 参数控制菜单显示区域。
• 触摸支持：添加 touchstart 事件监听，模拟点击行为。

$("#search-box").autocomplete({
  position: { my: "left top", at: "left bottom" },
  // 其他配置...
});

结论：掌握自动完成的实战价值

通过本文的讲解，读者应该能够理解如何使用 jQuery UI 的 Autocomplete 插件实现基础到复杂的功能。从静态建议到远程数据加载，从样式定制到事件处理，每个步骤都体现了“渐进增强”和“可维护性”的开发理念。

对于编程初学者，建议先通过静态数据熟悉插件的基本用法；中级开发者则可以尝试结合 AJAX、动态渲染和性能优化技巧，构建更复杂的交互场景。记住，优秀的自动完成功能不仅能提升用户体验，还能降低后端服务器的压力——例如，通过前端过滤减少不必要的 API 调用。

最后，鼓励读者访问 jQuery UI 官方文档 深入探索更多选项，并尝试将本文案例中的代码与实际项目结合，逐步完善自己的技术栈。