jQuery UI 实例 – 自动完成(Autocomplete)(手把手讲解)

更新时间:

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

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

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

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

前言:为什么选择自动完成功能?

在现代 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 提供了多个事件钩子,可用于扩展功能:

事件名触发时机常见用途
search用户输入内容变化时拦截或修改请求参数
focus鼠标悬停或键盘选中某建议项高亮显示或预览信息
select用户选择某建议项提交表单或跳转页面
open/close建议菜单弹出/关闭时动态加载数据或更新 UI

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

场景描述

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


实现步骤

  1. HTML 结构
<div class="search-container">
  <input type="text" id="city-search" placeholder="输入城市名称">
  <div class="result-message"></div>
</div>
  1. 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; }
  1. 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");
    }
  });
});
  1. 后端接口返回示例(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 官方文档 深入探索更多选项,并尝试将本文案例中的代码与实际项目结合,逐步完善自己的技术栈。

最新发布