@ a11y- oracle/ 键盘引擎

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

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

安装

npm install @a11y-oracle/keyboard-engine

使用量

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 ) .

支持的密钥

类型

KeyDefinition

单键的 CDP 键盘事件参数 :

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

用于按键组合的修改键 :

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

FocusedElementInfo

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

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 };
}

出口

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, 边框矩形) .