Bootstrap 5 需借助第三方库 bootstrap5-autocomplete 实现自动补全，初始化需确保 DOM 就绪、依赖加载顺序正确（bootstrap.bundle.min.js 在前），数据源格式合规，远程请求需匹配 resultset 结构并处理跨域与错误回调。
Bootstrap 5 本身不提供自动补全（autocomplete）功能，bootstrap5-autocomplete 是一个第三方扩展库，它在 Bootstrap 5 的 DOM 结构和事件体系上构建了可工作的自动补全组件。直接用原生 Bootstrap 5 的 form-control 或 dropdown 无法实现输入联想，必须引入该扩展或自行封装。
如何加载并初始化 bootstrap5-autocomplete 实例
核心是确保 DOM 就绪、依赖加载顺序正确，并传入符合格式的数据源。常见失败不是代码写错，而是路径或数据结构不匹配。
-
bootstrap5-autocomplete.min.js必须在bootstrap.bundle.min.js之后加载，否则会报Dropdown is not defined或document.getElementById(...) is null - 输入框需有明确的
id，初始化时通过该id绑定：new Autosuggest('myInputId', { ... }) - 本地数据必须是数组，每个元素为对象，且至少含
label和value字段（或通过displayKey/valueKey显式指定） - 远程数据需配置
url和method，返回体必须含resultset字段，且其值为数组——哪怕后端用的是 RESTful 风格，也得在onServerResponse中手动提取并 return 出{ resultset: [...] }
remote 模式下 axios 请求失败的典型表现与修复
错误信息如 TypeError: Cannot read properties of undefined (reading 'resultset') 或控制台静默无响应，大概率是服务器返回结构没对齐，而非网络问题。
- 默认期望后端返回
{ code: 200, message: "...", resultset: [...] }；若后端返回纯数组[...]，需在onServerResponse中包装：return { resultset: data } - axios 默认不带 credentials，跨域请求需显式设
withCredentials: true，并在服务端响应头加Access-Control-Allow-Credentials: true - 4xx/5xx 响应不会触发
onServerResponse，而是走onServerError回调——新版本才支持该回调，旧版只会console.error，容易被忽略 - 防抖延迟（
debounce）默认 300ms，若后端响应慢于该值，用户快速输入会 cancel 前序请求；可调高至500，但别设为0，否则每敲一个字符都发请求
键盘与鼠标焦点冲突导致的选择意外
组件默认启用“最后交互优先”焦点策略，这在混合操作时容易引发误选：比如用方向键选中第 3 项，鼠标一划过第 1 项，回车就提交了第 1 项。
- 禁用鼠标悬停聚焦，只保留键盘导航：初始化时加
mouseHover: false - 若需保留悬停效果，但防止覆盖键盘选择，可在
onSelect中记录一次“主动选择”，后续鼠标悬停不再触发focus，直到输入框失去焦点再重置 - 回车行为分两种：当前有高亮项时选中该项；输入框非空但无高亮时，应触发自定义提交（如搜索），这需监听
keydown拦截Enter并判断dropdown?.classList.contains('show') - 移动端点击选项后，输入框可能失焦导致下拉收起太快，建议加
touch-action: manipulation到下拉菜单容器，并在onSelect中手动input.focus()
清除按钮（clear button）的回调陷阱
点击右上角 × 清除输入内容时，onSelect 不会触发，很多人误以为清空=取消选择，结果状态没同步。
- 老版本无专用清除回调，只能靠监听
input事件比对value变化来识别“清空动作”，但无法区分是用户删光还是脚本赋值 - 新版支持
onClear回调，但要注意：它只在点击 × 时触发，不响应input.value = ""或input.dispatchEvent(new Event("input")) - 若需统一处理清空逻辑，建议封装一个
clearInput()方法，内部同时调用input.value = ""、触发input事件、并手动执行业务清理逻辑 - 清除后下拉菜单未关闭？检查是否忘了调用
instance.hide()——onClear不自动收起下拉
真正麻烦的不是 API 怎么写，而是交互边界：什么时候该用键盘、什么时候该信鼠标、清空算不算一次“选择”。这些细节不提前约定，上线后用户反馈的“点错了”“输一半没了”基本都卡在这儿。
