# @crowecawcaw/xa11y 中文文档

规范地址：https://npmcn.com/package/%40crowecawcaw/xa11y/

版本：0\.15\.4
npm 元数据更新时间：2026-10-24T13:00:12.838Z
中文译文更新时间：2026-11-11T01:51:51.255Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：144 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-04-18T15:56:25.529Z
- 最新版本发布：2026-10-24T13:00:12.350Z
- 近 30 天下载量：388933（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

用于 Node.js 的跨平台访问客户端库

## 安装

```sh
npm install @crowecawcaw/xa11y
```

也可以使用：`pnpm add @crowecawcaw/xa11y`、`yarn add @crowecawcaw/xa11y`、`bun add @crowecawcaw/xa11y`

## README

# @crowecawcaw/xa11y (英语)

[![npm](https://img.shields.io/npm/v/@crowecawcaw/xa11y)](https://www.npmjs.com/package/@crowecawcaw/xa11y) [![CI](https://github.com/xa11y/xa11y/actions/workflows/ci.yml/badge.svg)](https://github.com/xa11y/xa11y/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/xa11y/xa11y/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-xa11y.dev-blueviolet)](https://xa11y.dev/)

用于Node.js的跨平台无障碍库. 一个API用于macOS,Windows, 和 Linux —— 建在 Rust上方 [`xa11y`](https://github.com/xa11y/xa11y) 箱子,通过 [美洲狮](https://napi.rs/)。 。 。 .

**使用大小写 :** UI 测试, AI代理工具, 桌面自动化, 可访问性 审计.

**[文档](https://xa11y.dev/)** • 妇女 **[Java 脚本 API](https://xa11y.dev/api/javascript/)** • 妇女 **[烂API](https://docs.rs/xa11y)** • 妇女 **[Python API 密码](https://xa11y.dev/api/python/)**

## 快速实例

```js
import { App } from '@crowecawcaw/xa11y';

const safari = await App.byName('Safari');

// Find elements with CSS-like selectors via locator
for (const button of await safari.locator('button').elements()) {
  console.log(button.name);
}

// Interact with elements (re-resolves on every call)
await safari.locator('button[name="Submit"]').press();
await safari.locator('text_field[name^="Search"]').setValue('hello world');
```

## 安装

```bash
npm install @crowecawcaw/xa11y
```

要求节点.js 18或更新. 为 Linux (x64/arm64), macOS (x64/arm64), 和 Windows (x64/arm64).

> **马可斯:** 授予您的终端( 或运行节点的进程) 2 权限 内 **系统设置 ~ 隐私和安全**数字 : **无障碍** _财务报告和审定财务报表_ **屏幕 系统音频记录( S)** (macOS 26+). 无障碍让xa11y读取 AX 树。 二是需要读取窗口内容. 没有它,只有菜单 栏是可见的。 关于macOS 27和较新的,无障碍提供生活 **设备控制和数据访问** 窗关.

## 默认自动同步

触摸无障碍树的每个操作都是同步运行的 因此,节点事件循环永远不会被阻断。 财产获取器 打开 `Element` 截图是同步的,因为数据在前面被捕获.

```js
const app = await App.byName('com.example.MyApp');
const submit = await app.locator('button[name="Submit"]').element();

console.log(submit.role);   // sync — already captured
console.log(submit.enabled); // sync
await submit.children();    // async — re-queries the provider
```

## 自动等待定位器

行动方法 `Locator` 在元素出现之前对树进行投票 **可见** 财务报告和审定财务报表 **启用**最多5秒钟的预算,然后才采取行动。 这样一来 测试对UI的适应能力 同步地充斥.

```js
// Waits until the dialog appears AND its OK button is enabled, then clicks it.
await app.locator('dialog[name="Save Changes?"] button[name="OK"]').press();
```

## 订阅事件

订阅扩展节点 `EventEmitter`这样你就可以使用熟悉的 `.on()` 编号 : `.once()` 编号 : `.off()` API (英语). 事件在以下两种情况下都被释放: 特定类型名称和覆盖 `'event'` 名称。 打电话 `close()` (或 通过一个 `AbortSignal`),以拆掉订阅.

```js
const sub = await app.subscribe();
sub.on('focusChanged', (ev) => console.log('focus moved to', ev.target?.name));
sub.on('event', (ev) => console.log(ev.type, ev.appName));
// ... later
sub.close();
```

### 等待一个单一的事件

使用 `waitForEvent()` 用于 Playwright 风格的一发相等选项 上游和超时 :

```js
const [opened] = await Promise.all([
  app.waitForEvent('windowOpened'),
  app.locator('button[name="Settings"]').press(),
]);

// With predicate + timeout
const ev = await sub.waitForEvent('focusChanged', {
  predicate: (e) => e.target?.role === 'button',
  timeout: 3000,
});
```

### 中止符号支持

两者 `subscribe()` 财务报告和审定财务报表 `waitForEvent()` 接受一个 `AbortSignal` 页:1 取消 :

```js
const ctrl = new AbortController();
const sub = await app.subscribe({ signal: ctrl.signal });
sub.on('focusChanged', (ev) => { /* ... */ });
// ctrl.abort() closes the subscription automatically
```

## 错误

所有操作投放子类 `XA11yError`数字 :

| 类 | 何时 |
| --- | --- |
| `PermissionDeniedError` | 未获得无障碍许可(macOS) |
| `SelectorNotMatchedError` | `element()` / 动作未找到 |
| `ActionNotSupportedError` | 元素不支持动作 |
| `TimeoutError` | A 类 `wait*` 或自动等待预算已过期 |
| `InvalidSelectorError` | 错误的选择器或动作数据 |
| `PlatformError` | 其他操作系统级失败 |

抓住一个特定的子类,让其余的传播:

```js
import { App, SelectorNotMatchedError } from '@crowecawcaw/xa11y';

try {
  await app.locator('button[name="Submit"]').press();
} catch (err) {
  if (err instanceof SelectorNotMatchedError) {
    /* expected miss */
  } else {
    throw err;
  }
}
```

## 许可证

麻省理工学院——见 [自由主义](https://github.com/xa11y/xa11y/blob/main/LICENSE)。 。 。 .

## 常见问题

### @crowecawcaw/xa11y 是什么？

用于 Node\.js 的跨平台访问客户端库

### 如何安装 @crowecawcaw/xa11y？

在项目目录运行 npm install @crowecawcaw/xa11y，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 xa11y，可以用 npx xa11y 直接运行。

### @crowecawcaw/xa11y 支持 TypeScript 吗？

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

### @crowecawcaw/xa11y 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @crowecawcaw/xa11y 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @crowecawcaw/xa11y 可以商用吗？

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

### @crowecawcaw/xa11y 的下载量有多少？

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

### @crowecawcaw/xa11y 还在维护吗？

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