内容
# 真实无障碍
[](#状态)
[](./LICENSE)
[](https://www.npmjs.com/package/@real-a11y-dev/core)
[](https://www.npmjs.com/package/@real-a11y-dev/inspector)
[](https://nodejs.org)
适用于真实世界的无障碍工具 - 语义树提取、测试工具、React集成、Storybook面板、CLI用于Shell和CI审计、MCP服务器用于AI代理，以及Chrome扩展，所有功能都由同一引擎驱动。
> **测试版.** `0.1.x`版本的API可能会在`0.2.0`之前发生变化。欢迎反馈和问题 - 请参见下面的[状态](#状态)。
语义导航器取代了视觉浏览器渲染，改为交互式DOM/无障碍树视图。点击链接、填写表单、激活按钮 - 所有操作都通过树完成。如果您的页面作为树没有意义，那么它根本没有意义。
## 为什么
现有工具（Chrome DevTools、Axe、WAVE）将无障碍树显示为被动检查器。语义导航器则相反：树是界面。这种方式通过使用强制良好的语义HTML，使糟糕的结构通过使用立即显现。
## 软件包
| 软件包 | 描述 | npm |
|---------|-------------|-----|
| [`@real-a11y-dev/core`](./packages/core) | 树提取、数据模型、交互引擎 | [](https://www.npmjs.com/package/@real-a11y-dev/core) |
| [`@real-a11y-dev/serialize`](./packages/serialize) | 确定性文本序列化 - 完整树、标题大纲、选项卡序列 | [](https://www.npmjs.com/package/@real-a11y-dev/serialize) |
| [`@real-a11y-dev/validate`](./packages/validate) | ARIA语义验证（按节点+树级规则），aria-query支持 | [](https://www.npmjs.com/package/@real-a11y-dev/validate) |
| [`@real-a11y-dev/semantic-navigator-ui`](./packages/ui) | Preact树渲染组件 | [](https://www.npmjs.com/package/@real-a11y-dev/semantic-navigator-ui) |
| [`@real-a11y-dev/inspector`](./packages/inspector) | 与框架无关的交互式无障碍树面板 | [](https://www.npmjs.com/package/@real-a11y-dev/inspector) |
| [`@real-a11y-dev/testing`](./packages/testing) | 无头审计助手 - 快照、断言、`flow()`链 | [](https://www.npmjs.com/package/@real-a11y-dev/testing) |
| [`@real-a11y-dev/cli`](./packages/cli) | `real-a11y` shell命令 - 审计/树/大纲/选项卡/列表/检查/快照/差异/登录，CI级退出代码 | [](https://www.npmjs.com/package/@real-a11y-dev/cli) |
| [`@real-a11y-dev/mcp`](./packages/mcp) | 模型上下文协议服务器，向AI代理公开审计 | [](https://www.npmjs.com/package/@real-a11y-dev/mcp) |
| [`@real-a11y-dev/react`](./packages/react) | React钩子和`<SemanticNavigator />`组件 | [](https://www.npmjs.com/package/@real-a11y-dev/react) |
| [`@real-a11y-dev/storybook-addon`](./packages/storybook-addon) | Storybook 8+的每个故事的A11y树面板 | [](https://www.npmjs.com/package/@real-a11y-dev/storybook-addon) |
| [`extension`](./packages/extension) | 带有侧面板UI的Chrome扩展 | — |
## 快速入门
### npm软件包
```bash
npm install @real-a11y-dev/inspector
```
```ts
import { createInspector } from "@real-a11y-dev/inspector";
const nav = createInspector({
root: document.getElementById("app"),
container: document.getElementById("tree-panel"),
viewMode: "a11y", // "dom" | "a11y"
interactive: true,
theme: "auto", // "light" | "dark" | "auto"
});
nav.mount();
```
### CLI
从您的shell中审计页面 - 并在CI中设置门槛。Playwright是一个可选的同伴依赖项（安装它来审计实时URL；本地HTML文件不需要浏览器）：
```bash
npm i -D @real-a11y-dev/cli@beta # 测试版dist-tag，适用于整个预发布系列
npx playwright install chromium
npx real-a11y audit https://example.com
```
`real-a11y audit`在屏幕阅读器保真度检查上退出非零 - 一个CI门槛，无需配置。完整的命令集（`tree`、`outline`、`tabs`、`list`、`inspect`、`snapshot`、`diff`、`login`）在[`@real-a11y-dev/cli`](./packages/cli)中有文档记录。
### MCP服务器（用于AI代理）
将审计和语义树公开给任何模型上下文协议客户端 - `npx -y`在首次运行时获取软件包：
```bash
npx -y @real-a11y-dev/mcp
```
服务器提供诸如`audit_page`（每个违规行为的结构化发现）和`get_semantic_tree`（角色+可访问名称大纲）等工具。要审计登录后的页面，请将`REAL_A11Y_MCP_STORAGE_STATE`指向保存的Playwright会话，并设置`REAL_A11Y_MCP_ALLOWED_ORIGINS`以将审计固定到受信任的源。参见[`@real-a11y-dev/mcp`](./packages/mcp)。
### Chrome扩展
[从Chrome Web Store安装](https://chromewebstore.google.com/detail/semantic-navigator/gnnepgbbecnlomngfemkadnbeaopleom)。Chrome可能会在首次安装时显示“谨慎操作 - 未受增强安全浏览信任”的通知；这是任何新列出的扩展的默认设置，而不是关于此扩展的特定信号 - 点击**继续安装**。
从源代码运行：
1. 克隆此仓库
2. 运行`pnpm install && pnpm build`
3. 打开`chrome://extensions`，启用开发者模式
4. 点击“加载解包”并选择`packages/extension/dist`
5. 导航到任意页面并点击语义导航器图标以打开侧面板
## 功能
### 两棵树视图（可切换）
- **DOM树** - 原始HTML元素，带有标签名、属性和文本内容
- **无障碍树** - 角色、可访问名称和状态（屏幕阅读器看到的内容）。通用/装饰节点被展平
### 完整的交互性
不仅仅是查看 - 通过树与页面交互：
- **点击**链接和按钮
- **导航**到链接目的地
- **聚焦**表单输入
- **切换**详细信息/摘要元素
- **提交**表单
### 键盘导航
遵循[WAI-ARIA TreeView模式](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/):
| 键 | 操作 |
|-----|--------|
| `向下箭头/向上箭头` | 在节点之间移动 |
| `向右箭头` | 展开节点或移动到第一个子节点 |
| `向左箭头` | 折叠节点或移动到父节点 |
| `回车` | 激活节点的 primary 操作 |
| `空格` | 切换展开/折叠 |
| `首页/结束` | 跳转到第一个/最后一个节点 |
| `*` | 展开所有同级节点 |
### 搜索和筛选
键入以跨标签名、角色、可访问名称、属性和文本内容进行搜索。匹配的节点及其祖先保持可见。
### 实时更新
树在DOM更改时自动更新（通过MutationObserver，带有防抖重提取）。
### 节点高亮
在树中悬停或选择一个节点，以查看页面上相应的元素高亮显示。
## 架构
```
core ──── serialize ─┐
├── testing ──── mcp ──── cli （无头 - 无UI依赖）
validate ────────────┘
core ──── ui ──┬── inspector ──┬── react
│ │
│ └── storybook-addon
extension ──→ ui ──→ core
```
- **core** - 无UI依赖。树提取（TreeWalker）、角色映射（80+ HTML元素到ARIA角色）、交互引擎（ActionDispatcher）、DOM观察、查询助手（`findByRole`、`linearize`、`getOutline`、`getTabSequence`、`diffTrees`）
- **serialize** - 树的确定性文本序列化：完整树、标题大纲和选项卡序列。依赖于core
- **validate** - ARIA语义验证（按节点规则+树级关系检查，如交互式嵌套和所需上下文/拥有）。aria-query支持，因此它永远不会偏离规范 - 独立（无核心依赖）
- **ui** - Preact组件（≈5KB gzipped - TreeView入口，参见`.size-limit.json`）。TreeView、TreeNode、带有自包含CSS和浅色/深色主题的TreeToolbar
- **inspector** - 与框架无关的嵌入。默认情况下使用Shadow-DOM隔离；可选地进行宿主应用副作用
- **testing** - 无头审计助手（`auditSnapshot`、`assertHeadingOrder`、`flow()`、Vitest序列化器、Playwright适配器）。组合core + serialize + validate；无UI依赖
- **cli** - `real-a11y` shell命令（audit、tree、outline、tabs、list、inspect、snapshot、diff、login），具有CI级退出代码和机器格式。基于测试引擎（通过mcp）
- **mcp** - 模型上下文协议服务器，向AI代理公开审计和语义树（`audit_page`、`get_semantic_tree`，...）。基于测试引擎
- **react** - `useSemanticTree`和`useActiveModal`钩子（通过`useSyncExternalStore`支持并发模式）以及`<SemanticNavigator />`组件
- **storybook-addon** - Storybook 8+的每个故事的A11y树面板
- **extension** - Chrome MV3。内容脚本提取树并分派操作；侧面板渲染树UI；后台服务工作线程路由消息
## 开发
```bash
# 安装依赖项
pnpm install
# 构建所有软件包
pnpm build
# 运行测试
pnpm test
# 监视模式（所有软件包）
pnpm dev
```
### 要求
- Node.js >= 20
- pnpm >= 9
## 技术栈
- TypeScript（严格模式）
- pnpm工作区
- Preact 10（3KB，React兼容API）
- tsup（core、ui、npm打包）
- Vite（扩展打包）
- Vitest + jsdom（测试）
## 状态
真实无障碍（Real A11y）处于**公开测试**阶段（`0.1.x`）。核心提取引擎和Chrome扩展稳定且在生产环境中使用；npm软件包（`@real-a11y-dev/inspector`、`@real-a11y-dev/testing`、`@real-a11y-dev/react`、`@real-a11y-dev/storybook-addon`）较新，可能会在`0.2.0`之前进行小幅度API更改。
关于什么是破坏性更改、什么是内部与公共以及弃用如何工作的约定在[docs/STABILITY.md](./docs/STABILITY.md)中。
在[SECURITY.md](./SECURITY.md)中查看如何报告安全问题，以及在打开问题或PR之前查看[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。
## 许可证
MIT - 请参阅[LICENSE](./LICENSE)
## 关于真实无障碍
> “真正的无障碍是构建适用于真实人在真实条件下使用的数字产品的实践。”
在[real-a11y.dev](https://real-a11y.dev)了解更多信息
