at.js 是一个轻量级的 JavaScript 库，主要用于实现文本输入框中的自动补全功能，常见于社交平台、评论系统等需要@提及、标签补全的场景，其核心行为通过参数配置实现，合理设置参数能让开发者精准控制触发条件、数据交互、UI 展示等逻辑，以下从参数类型、作用场景及示例出发，详细解析 at.js 的关键参数。
at.js 参数详解
at.js 的参数通过初始化时传入对象配置，主要可分为触发控制、数据交互、UI 展示、回调函数四大类，具体参数如下表所示：
| 参数名 | 类型 | 默认值 | 作用说明 | 示例 |
|---|---|---|---|---|
trigger |
String | 设置触发自动补全的字符，支持多字符（如 ‘#@’）或正则表达式。 | trigger: '@'（触发@提及）；trigger: '#@'（需输入#@才触发） |
|
searchKey |
String | ‘value’ | 指定数据源中用于搜索的字段名，与后端返回数据字段对应。 | 若后端返回 {id: 1, name: '张三'}，则 searchKey: 'name' |
displayTpl |
String | ‘
‘ | 下拉列表项的 HTML 模板，支持通过 ${字段名} 插入数据。 | displayTpl: '<li><img src="${avatar}"/>${name}</li>'（显示头像和姓名） |
insertTpl | String | ‘${value}’ | 选中补全项后插入输入框的内容模板，可自定义格式（如带链接、标签）。 | insertTpl: '@${name}（${id}）'（插入@张三（1）） |
delay | Number | 300 | 输入触发字符后，发送搜索请求的延迟时间（毫秒），避免频繁请求。 | delay: 500（输入后等待500ms再请求） |
maxItems | Number | 5 | 下拉列表最大显示数量，超出部分滚动显示。 | maxItems: 10（最多显示10条补全项） |
minChars | Number | 0 | 触发补全所需的最小字符数（如输入@后需再输入1个字符才触发搜索）。 | minChars: 1（输入@后需再输入至少1个字符） |
hideDropdownOnSelect | Boolean | true | 选中补全项后是否自动隐藏下拉框。 | hideDropdownOnSelect: false（选中后仍显示下拉框） |
highlightFirst | Boolean | false | 是否自动高亮下拉列表的第一项，支持回车键快速选中。 | highlightFirst: true（默认选中第一项） |
callbacks | Object | 配置生命周期回调函数，包括请求前、请求后、选中后等钩子。 | 见下方“回调函数参数说明” |
回调函数参数说明
callbacks 是 at.js 最灵活的部分，通过不同回调函数可自定义数据请求、数据处理逻辑：
beforeQuery(query, callback)：发送请求前的回调，query为当前输入内容，callback控制是否请求（如callback({results: []})可直接返回数据）。
示例：过滤空请求callbacks: { beforeQuery: function (query, callback) { if (query.length < 2) callback({results: []}); // 输入不足2字符不请求 else callback(); } }afterRender($ul)：下拉列表渲染后的回调，$ul为 jQuery 对象，可自定义样式或事件。
示例：为列表项添加点击事件afterRender: function ($ul) { $ul.find('li').on('click', function () { console.log('选中项:', $(this).data('item')); }); }afterInsert(value, $input)：选中项插入输入框后的回调，value为插入内容，$input为输入框元素。
示例：插入后清空输入框（如标签场景）afterInsert: function (value, $input) { $input.val(''); // 插入后清空输入，继续输入新标签 }
参数组合应用示例
实现一个带头像的@提及功能，后端返回 {id: 1, name: '张三', avatar: 'url'}，配置如下：
$('#input').atwho({
at: '@', // 触发字符为@
searchKey: 'name', // 搜索name字段
displayTpl: '<li><img src="${avatar}" width="20"/>${name}</li>', // 显示头像和姓名
insertTpl: '@${name}', // 插入@张三
delay: 400, // 400ms延迟请求
maxItems: 8, // 最多显示8条
callbacks: {
afterInsert: function (value, $input) {
console.log('插入内容:', value); // 插入后打印日志
}
}
});
相关问答 FAQs
Q1：at.js 参数中的 beforeQuery 和 afterQuery 有什么区别？
A：beforeQuery 在发送请求前触发，可修改请求数据或直接返回本地数据（避免请求后端），适合缓存或过滤场景；afterQuery 在收到后端响应后触发，可对返回数据二次处理（如格式化、过滤空值），但无法阻止请求发送。beforeQuery 可判断本地是否有缓存数据，有则直接返回；afterQuery 可将后端返回的 {data: [...]} 提取为 [...] 供 at.js 渲染。
Q2：如何通过 at.js 参数实现自定义的@提及样式？
A：通过 displayTpl 参数自定义 HTML 模板，结合 CSS 样式实现，设置 displayTpl: '<li class="mention-item"><span class="name">${name}</span><span class="id">#${id}</span></li>'，并在 CSS 中定义 .mention-item { display: flex; align-items: center; padding: 5px; } .name { font-weight: bold; } .id { color: #999; margin-left: 5px; }，即可实现带姓名和ID的@提及样式，同时通过 afterRender 回调可添加动态交互（如悬停高亮）。
原创文章，发布者：酷番叔，转转请注明出处：https://cloud.kd.cn/ask/47782.html
