# @a11y-oracle/keyboard-engine 中文文档

规范地址：https://npmcn.com/package/%40a11y-oracle/keyboard-engine/

版本：1\.3\.2
npm 元数据更新时间：2026-03-12T05:47:15.402Z
中文译文更新时间：2026-11-06T00:46:10.621Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40a11y-oracle/keyboard-engine
原文对照：https://npmcn.com/package/%40a11y-oracle/keyboard-engine/?lang=original
项目主页：https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/keyboard-engine
源码仓库：https://github.com/a11y-oracle/a11y-oracle

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

- 包体积（解压后）：19.7 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-03-04T19:25:01.185Z
- 最新版本发布：2026-03-12T05:47:15.252Z
- 近 30 天下载量：7851（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

原生 CDP 键盘调度, 并带有修改键支持和焦点元素内移

## 安装

```sh
npm install @a11y-oracle/keyboard-engine
```

也可以使用：`pnpm add @a11y-oracle/keyboard-engine`、`yarn add @a11y-oracle/keyboard-engine`、`bun add @a11y-oracle/keyboard-engine`

## README

# @ a11y- oracle/ 键盘引擎

CDP基于无障碍测试的键盘调度引擎. 通过本地硬件级别按键发送 `Input.dispatchKeyEvent` 并读取焦点要素信息 `Runtime.evaluate`。 。 。 .

这是内部使用的低层构件 `@a11y-oracle/core-engine`。大多数用户应该使用 Playwright 或 Cypress 插件.

## 安装

```bash
npm install @a11y-oracle/keyboard-engine
```

## 使用量

```typescript
import { KeyboardEngine } from '@a11y-oracle/keyboard-engine';

const keyboard = new KeyboardEngine(cdpSession);

// Press a key
await keyboard.press('Tab');

// Press with modifiers
await keyboard.press('Tab', { shift: true });   // Shift+Tab (backward)
await keyboard.press('a', { ctrl: true });       // Ctrl+A (select all)

// Get info about the currently focused element
const el = await keyboard.getFocusedElement();
if (el) {
  console.log(el.tag);      // "BUTTON"
  console.log(el.id);       // "submit-btn"
  console.log(el.role);     // "button"
  console.log(el.tabIndex); // 0
  console.log(el.rect);     // { x: 100, y: 200, width: 120, height: 40 }
}
```

## API 参考

### `KeyboardEngine`

#### `constructor(cdp: CDPSessionLike)`

创建新的键盘引擎 .

-   `cdp` - 任何具有下列特性的物体: `send(method, params?)` 方法与 CDP 兼容.

#### `press(key: string, modifiers?: ModifierKeys): Promise<void>`

通过 CDP 发送本地密钥 `Input.dispatchKeyEvent`发送 `keyDown` 之后的活动 `keyUp` ,匹配物理密钥按键的行为.

-   `key` - 关键名称来自 `KEY_DEFINITIONS` (见下表).
-   `modifiers` ——新闻出版期间可选修饰键.

修改 CDP 位图的密钥映射: Alt = 1, Ctrl = 2, Meta = 4, Shift = 8.

如果密钥名称不在则丢出 `KEY_DEFINITIONS`。 。 。 .

#### `getFocusedElement(): Promise<FocusedElementInfo | null>`

获取关于当前聚焦 DOM 元素的信息 `Runtime.evaluate`。 。 。 .

回返 `null` 如果没有互动要素有重点(例如, `document.body` 或者说 `document.documentElement` ) .

### 支持的密钥

| 密钥名称 | 说明 |
| --- | --- |
| `Tab` | 标签导航 |
| `Enter` | 激活/提交 |
| `Space` 或者说 `' '` | 激活/切换 |
| `Escape` | 取消/ 关闭 |
| `ArrowUp` | 导航 |
| `ArrowDown` | 导航 |
| `ArrowLeft` | 导航左边 |
| `ArrowRight` | 向右导航 |
| `Home` | 跳转到开始 |
| `End` | 跳至结束 |
| `Backspace` | 向后删除 |
| `Delete` | 向前删除 |

### 类型

#### `KeyDefinition`

单键的 CDP 键盘事件参数 :

```typescript
interface KeyDefinition {
  key: string;     // CDP key property (e.g. "Tab")
  code: string;    // CDP code property (e.g. "Tab")
  keyCode: number; // Windows virtual key code (e.g. 9)
}
```

#### `ModifierKeys`

用于按键组合的修改键 :

```typescript
interface ModifierKeys {
  shift?: boolean;
  ctrl?: boolean;
  alt?: boolean;
  meta?: boolean;
}
```

#### `FocusedElementInfo`

关于当前重点DOM元素的信息:

```typescript
interface FocusedElementInfo {
  tag: string;        // "BUTTON"
  id: string;         // "submit-btn"
  className: string;  // "btn primary"
  textContent: string; // "Submit"
  role: string;       // "button" (from role attribute)
  ariaLabel: string;  // "Submit form" (from aria-label)
  tabIndex: number;   // 0
  rect: { x: number; y: number; width: number; height: number };
}
```

## 出口

```typescript
export { KeyboardEngine } from '@a11y-oracle/keyboard-engine';
export { KEY_DEFINITIONS } from '@a11y-oracle/keyboard-engine';
export type {
  KeyDefinition,
  ModifierKeys,
  FocusedElementInfo,
} from '@a11y-oracle/keyboard-engine';
```

## 如何运作

该引擎使用两个 CDP 域:

1.  **`Input.dispatchKeyEvent`** ——直接向浏览器发送真实的硬件级别按键事件(keyDown + keyUp). 绕过合成 JavaScript 事件发送(`element.dispatchEvent()`)),因此浏览器以本土方式处理焦点管理——就像用户实际按下密钥一样.
    
2.  **`Runtime.evaluate`** 执行页面上下文中的 JavaScript 表达式 `document.activeElement` 属性(tag, id, 类, 角色, aria- label, tabIndex, 边框矩形) .

## 常见问题

### @a11y-oracle/keyboard-engine 是什么？

原生 CDP 键盘调度, 并带有修改键支持和焦点元素内移

### 如何安装 @a11y-oracle/keyboard-engine？

在项目目录运行 npm install @a11y-oracle/keyboard-engine，或使用 pnpm add / yarn add / bun add。

### @a11y-oracle/keyboard-engine 支持 TypeScript 吗？

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

### @a11y-oracle/keyboard-engine 支持 ESM 还是 CommonJS？

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

### @a11y-oracle/keyboard-engine 可以商用吗？

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

### @a11y-oracle/keyboard-engine 的下载量有多少？

根据 npm 官方下载统计，@a11y-oracle/keyboard-engine 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,851 次，日均约 262 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @a11y-oracle/keyboard-engine 还在维护吗？

最新版本 1\.3\.2 发布于 2026/03/12（7 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/03/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。