# @github/combobox-nav 中文文档

规范地址：https://npmcn.com/package/%40github/combobox-nav/

版本：3\.0\.2
npm 元数据更新时间：2026-10-15T16:20:37.548Z
中文译文更新时间：2026-11-16T10:49:27.958Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40github/combobox-nav
原文对照：https://npmcn.com/package/%40github/combobox-nav/?lang=original
项目主页：https://github.com/github/combobox-nav#readme
源码仓库：https://github.com/github/combobox-nav

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.2 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-11-07T17:30:51.776Z
- 最新版本发布：2026-06-30T17:20:19.354Z
- 近 30 天下载量：297724（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 1 个）

## 中文简介

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

## 安装

```sh
npm install @github/combobox-nav
```

也可以使用：`pnpm add @github/combobox-nav`、`yarn add @github/combobox-nav`、`bun add @github/combobox-nav`

## README

# 组合框导航

附加 [组合框导航行为( ARIA 1.2)](https://www.w3.org/TR/wai-aria-1.2/#combobox) 改为 `<input>`。 。 。 .

## 安装

```
$ npm install @github/combobox-nav
```

## 使用量

### HTML 语言

```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"`

### 联合来文

```js
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` 当通过键盘或单击选择一个选项时,事件会在列表元素上开火.

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

```js
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` 当选定一个选项但尚未执行时,该事件会被点入列表元素.

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

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

## 设置

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

```js
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"]` 键盘导航,选中的元素将被调用到 [元素. 滚动到视频](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView)。配置此值以控制滚动行为(或 `boolean` 或一个 [滚动到视频选项](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#sect1) 对象.

## 发展

```
npm install
npm test
```

## 常见问题

### @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 和提交记录判断。

