@github/combobox-nav

中文文档
3.0.2发布于 2026/07/01MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 29.8万

将组合框导航行为附加到输入中.

中文使用文档
文档目录7 节
  1. 安装
  2. 使用量
  3. HTML 语言
  4. 联合来文
  5. 活动
  6. 设置
  7. 发展

组合框导航

附加 组合框导航行为( ARIA 1.2) 改为 <input>。 。 。 .

安装

$ npm install @github/combobox-nav

使用量

HTML 语言

<label>
  Robot
  <input id="robot-input" type="text" />
</label>
<ul role="listbox" id="list-id" hidden>
  <li id="baymax" role="option">Baymax</li>
  <li><del>BB-8</del></li>
  <!-- `role=option` needs to be present for item to be selectable -->
  <li id="hubot" role="option">Hubot</li>
  <li id="r2-d2" role="option">R2-D2</li>
</ul>

标记要求 :

  • 每个选项都需要有 role="option" 和一个独特的 id
  • 名单应该有 role="listbox"

联合来文

import Combobox from '@github/combobox-nav'
const input = document.querySelector('#robot-input')
const list = document.querySelector('#list-id')

// install combobox pattern on a given input and listbox
const combobox = new Combobox(input, list)
// when options appear, start intercepting keyboard events for navigation
combobox.start()
// when options disappear, stop intercepting keyboard events for navigation
combobox.stop()

// move selection to the nth+1 item in the list
combobox.navigate(1)
// reset selection
combobox.clearSelection()
// uninstall combobox pattern from the input
combobox.destroy()

活动

A combobox-commit 当通过键盘或单击选择一个选项时,事件会在列表元素上开火.

例如,在选择一个选项时自动完成 :

list.addEventListener('combobox-commit', function (event) {
  console.log('Element selected: ', event.target)
})

说明 使用时 <label> + 键 <input> 作为选项,请听 change 改为 combobox-commit。 。 。 .

当标签被点击时, click 事件均被发射 <label> 及其相关投入 label.control由于组合框不知道控制, combobox-commit 无法用作项目选择状态的指标.

A combobox-select 当选定一个选项但尚未执行时,该事件会被点入列表元素.

例如,在选择一个选项但尚未执行时自动完成 :

list.addEventListener('combobox-select', function (event) {
  console.log('Element selected : ', event.target)
})

设置

对于高级配置,构造器会选择第三个参数. 例如:

const combobox = new Combobox(input, list, {tabInsertsSuggestions: true})

这些设置可用 :

  • tabInsertsSuggestions: boolean = true - 控制在何时插入突出建议 标签 已按下 (输入 将始终插入一个建议,不论设置如何)。 何时 true,标签导航会在打开时被劫持(这可能会对无障碍性产生不利影响),但组合框会更紧密地模仿本土的IDE体验.
  • firstOptionSelectionMode: FirstOptionSelectionMode = 'none' - 此选项指定了默认行为, 当尚未选择任何选项, 而用户按下 输入下列数值: FirstOptionSelectionMode 将采取以下行动:
    • 'none':不要自动选择第一个选项.
    • 'active': 将第一个选项置于未选中的“ 活动” 状态( 不是 aria-activedescendant),但如果用户按下 Enter。要选择第二个项目,用户需要按下两次箭头。 这种方法可以在不干扰屏幕阅读器用户的情况下快速应用选择.

    3⁄4 ̄ ̧漯B 屏幕阅读器不会宣布第一个项目是默认的. 这一点应明确宣布,使用 aria-live 状态

    • 'selected':通过导航选择第一个项目。 这使得可以快速应用选择,并使得选择第二个项目的速度更快,但对于屏幕阅读器用户来说可能具有干扰性或混乱.
  • scrollIntoViewOptions?: boolean | ScrollIntoViewOptions = undefined - 当 控制标记的元素 [aria-selected="true"] 键盘导航,选中的元素将被调用到 元素. 滚动到视频。配置此值以控制滚动行为(或 boolean 或一个 滚动到视频选项 对象.

发展

npm install
npm test

版本与发布记录

@github/combobox-nav 共发布 25 个版本,首次发布于 2018/11/08;过去 12 个月发布了 1 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.2latest2026/07/014 个月前
3.0.12024/02/272 年前
3.0.02024/02/232 年前
2.3.12023/12/242 年前
2.3.02023/09/253 年前
2.2.02023/09/153 年前

关于 @github/combobox-nav 的常见问题

@github/combobox-nav 是什么?

将组合框导航行为附加到输入中.

如何安装 @github/combobox-nav?

在项目目录运行 npm install @github/combobox-nav,或使用 pnpm add / yarn add / bun add。

@github/combobox-nav 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@github/combobox-nav 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@github/combobox-nav 可以商用吗?

@github/combobox-nav 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@github/combobox-nav 的下载量有多少?

根据 npm 官方下载统计,@github/combobox-nav 在 2026/10/17 – 2026/11/15 这 30 天内被下载 297,724 次,日均约 9,924 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@github/combobox-nav 还在维护吗?

最新版本 3.0.2 发布于 2026/07/01(4 个月前);至今共发布 25 个版本,其中过去 12 个月发布了 1 个;首次发布于 2018/11/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。