# @a11y-oracle/audit-formatter 中文文档

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

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

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

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

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

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

## 中文简介

将访问结果转换为轴- 核心兼容 Oracle Isue 对象与 WCAG 规则元数据

## 安装

```sh
npm install @a11y-oracle/audit-formatter
```

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

## README

# @ a11y- oracle/ 审计- formatter

将 A11y- Oracle 解析结果转换为轴- 核心相容的发件对象( )`OracleIssue`) (中文(简体) ). 纯函数,不依赖 CDP —— 与任何 `A11yState` 或者说 `TraversalResult` 不论如何生产.

产出与核心结果的区别 `resultType: 'oracle'` 财务报告和审定财务报表 `oracle/`\- 前置规则ID(例如, `oracle/focus-not-visible`) (中文(简体) ).

## 安装

```bash
npm install @a11y-oracle/audit-formatter
```

> **说明:** 大多数用户应使用 [`@a11y-oracle/playwright-plugin`](https://npmcn.com/package/%40a11y-oracle/playwright-plugin/README.md) 或者说 [`@a11y-oracle/cypress-plugin`](https://npmcn.com/package/%40a11y-oracle/cypress-plugin/README.md) 换句话说 这些插件使用的基本库是审计前事项。 如果您需要在测试框架外格式化问题或构建自定义集成,则直接安装它.

## 使用量

### 纯格式函数

最简单的办法——通过 `A11yState` 并回到任何问题:

```typescript
import { formatFocusIssues, formatTrapIssue } from '@a11y-oracle/audit-formatter';
import type { A11yState } from '@a11y-oracle/core-engine';
import type { TraversalResult } from '@a11y-oracle/focus-analyzer';

const context = { project: 'my-app', specName: 'nav.spec.ts' };

// Check a focused element for focus indicator issues
const focusIssues = formatFocusIssues(state, context);
// Returns: [] if passing, or [OracleIssue] if failing

// Check a traversal result for keyboard traps
const trapIssues = formatTrapIssue(result, '#modal-container', context);
// Returns: [] if not trapped, or [OracleIssue] if trapped

// Convenience: run all state-based checks at once
import { formatAllIssues } from '@a11y-oracle/audit-formatter';
const allIssues = formatAllIssues(state, context);
```

### 甲骨文审计师类

包装一个管弦乐手,并自动审核每一次互动. 问题在各种呼吁中不断累积:

```typescript
import { test, expect } from '@a11y-oracle/playwright-plugin';
import { OracleAuditor } from '@a11y-oracle/audit-formatter';

test('all focus indicators pass oracle rules', async ({ page, a11y }) => {
  await page.goto('/my-page.html');

  const auditor = new OracleAuditor(a11y, {
    project: 'my-app',
    specName: 'navigation.spec.ts',
  });

  // Each pressKey() automatically runs all state-based checks
  await auditor.pressKey('Tab');
  await auditor.pressKey('Tab');
  await auditor.pressKey('Tab');

  // Check a container for keyboard traps
  await auditor.checkTrap('#modal-container');

  // Assert no issues found
  expect(auditor.issueCount).toBe(0);
  expect(auditor.getIssues()).toHaveLength(0);
});
```

这个 `OracleAuditor` 接受任何匹配对象 `OrchestratorLike` 接口,两者都满意 `A11yOracle` (弗莱特)和 `A11yOrchestrator` (核心发动机).

### 选择器公用事业

从元素数据生成 CSS 选择器和 HTML 片断 :

```typescript
import {
  selectorFromFocusedElement,
  htmlSnippetFromFocusedElement,
} from '@a11y-oracle/audit-formatter';

const selector = selectorFromFocusedElement(state.focusedElement);
// "#submit-btn" or "button.primary.large" or "button"

const snippet = htmlSnippetFromFocusedElement(state.focusedElement);
// '<button id="submit-btn" class="primary">Submit</button>'
```

## 规则

A11y-Oracle执行6个WCAG规则:

| 规则ID | WCAG 标准 | 自兹 | 职等 | 标记 | 影响 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `oracle/focus-not-visible` | [2.4.7 焦点可见](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) | 2.0 数据 | AA 对 | `wcag2aa` | `serious` | 重点要素没有明显的重点指标 |
| `oracle/focus-low-contrast` | [2.4.12 重点外观](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) | 2.2 国家 | AA 对 | `wcag22aa` | `moderate` | 重点指标对比率低于3:1 |
| `oracle/keyboard-trap` | [2.1.2 无键盘陷阱](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) | 2.0 数据 | A 类 | `wcag2a` | `critical` | 键盘焦点被困入容器 |
| `oracle/focus-missing-name` | [4.1.2 名称、作用、价值](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | 2.0 数据 | A 类 | `wcag2a` | `serious` | 焦点元素没有可访问的名称 |
| `oracle/focus-generic-role` | [4.1.2 名称、作用、价值](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | 2.0 数据 | A 类 | `wcag2a` | `serious` | 重点要素具有一般或列报作用 |
| `oracle/positive-tabindex` | [2.4.3 重点顺序](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | 2.0 数据 | A 类 | `wcag2a` | `serious` | 元素使用正标签索引值 |

`focus-not-visible` 拥有优先级 `focus-low-contrast` ——如果没有指标,只有能见度规则起火(并非两者兼有). `focus-generic-role` 财务报告和审定财务报表 `focus-missing-name` 它们是相互排斥的——一般角色只触发角色检查.

关于每项规则的详细补救指导意见,见 [补救指南](https://npmcn.com/package/docs/REMEDIATION.md)。 。 。 .

## API 参考

### 函数

#### `formatFocusIssues(state, context)`

检查一个 `A11yState` 关于重点指标问题.

-   **参数:**
    -   `state: A11yState` ——统一无障碍状态从 `pressKey()` 或者说 `getState()`
    -   `context: AuditContext` —— 说 `{ project, specName, wcagLevel?, disabledRules? }`
-   **回返情况:** `OracleIssue[]` 0或1个问题
-   **行为:** 回返 `oracle/focus-not-visible` 若为 `isVisible === false`. 回归 `oracle/focus-low-contrast` 如果可见,但 `meetsWCAG_AA === false`. 回归 `[]` 如果通过或没有焦点元素.

#### `formatTrapIssue(result, containerSelector, context)`

检查a `TraversalResult` 用于键盘陷阱.

-   **参数:**
    -   `result: TraversalResult` ——因 `traverseSubTree()`
    -   `containerSelector: string` - 集装箱的CSS选择器(用于本问题)
    -   `context: AuditContext` —— 说 `{ project: string, specName: string }`
-   **回返情况:** `OracleIssue[]` 0或1个问题

#### `formatNameIssues(state, context)`

检查一个 `A11yState` 对于缺失的无障碍名称问题.

-   **参数:** 与 `formatFocusIssues`
-   **回返情况:** `OracleIssue[]` 0或1个问题
-   **行为:** 回返 `oracle/focus-missing-name` 如果焦点元素没有计算名称。 跳过具有通用/演示角色的元素(那些起火) `formatRoleIssues` 页:1.

#### `formatRoleIssues(state, context)`

检查一个 `A11yState` 一般性/介绍性作用问题.

-   **参数:** 与 `formatFocusIssues`
-   **回返情况:** `OracleIssue[]` 0或1个问题
-   **行为:** 回返 `oracle/focus-generic-role` 如果焦点元素有一个 `generic`, (中文(简体) ), `none`,或 `presentation` 角色。 。 .

#### `formatTabIndexIssues(state, context)`

检查一个 `A11yState` 用于正标签索引问题.

-   **参数:** 与 `formatFocusIssues`
-   **回返情况:** `OracleIssue[]` 0或1个问题
-   **行为:** 回返 `oracle/positive-tabindex` 如果焦点元素有 `tabIndex > 0`。 。 。 .

#### `formatAllIssues(state, context)`

运行所有基于国家的检查的方便包装:焦点指示器、名称、角色和标签索引.

-   **参数:** 与 `formatFocusIssues`
-   **回返情况:** `OracleIssue[]`
-   **行为:** 应用 `wcagLevel` 过滤( 默认) `'aa'`和 `disabledRules` 从 `context`。 。 。 .

#### `matchesWcagLevel(rule, level)`

检查某一规则是否适用于特定WCAG的合规级别.

-   **参数:**
    -   `rule: OracleRule` ——规则元数据对象
    -   `level: WcagLevel` —— 说 `'a'` 或者说 `'aa'`
-   **回返情况:** `boolean` —— 说 `true` 如果该规则适用于指定的级别
-   **行为:** `'aa'` 包括所有规则. `'a'` 仅包括贴有标签的规则 `wcag2a`。 。 。 .

### 甲骨文审计师

#### `constructor(orchestrator, context)`

-   `orchestrator: OrchestratorLike` - 任何对象 `pressKey()`, (中文(简体) ), `getState()`,以及 `traverseSubTree()` 方法
-   `context: AuditContext` —— 说 `{ project, specName, wcagLevel?, disabledRules? }`

#### `pressKey(key, modifiers?): Promise<A11yState>`

调出一个关键媒体,并自动审计所有基于国家的规则的结果状态.

#### `getState(): Promise<A11yState>`

读取当前状态并审计所有基于状态的规则.

#### `checkTrap(selector, maxTabs?): Promise<TraversalResult>`

在容器上运行键盘陷阱检测并审核结果.

#### `getIssues(): ReadonlyArray<OracleIssue>`

退回所有累计发行的相册.

#### `clear(): void`

重置累积的问题清单.

#### `issueCount: number`

累计发行数量(完善).

### Orchestrator 类似接口

```typescript
interface OrchestratorLike {
  pressKey(key: string, modifiers?: Record<string, boolean>): Promise<A11yState>;
  getState(): Promise<A11yState>;
  traverseSubTree(selector: string, maxTabs?: number): Promise<TraversalResult>;
}
```

满意的 `A11yOracle` (剧作家插座)和 `A11yOrchestrator` (核心发动机).

### 水电费

#### `RULES: Record<string, OracleRule>`

所有被规则 ID 键入的定义规则对象 .

#### `RULE_IDS: string[]`

所有规则ID的组合.

#### `getRule(ruleId): OracleRule`

通过身份证明获得规则,或者在未知的情况下丢出规则.

### 选择器公用事业

#### `selectorFromFocusedElement(el): string`

从一个 CSS 创建 CSS 选择器 `A11yFocusedElement`优先级: `#id` > 翻译: `tag.class1.class2` > 翻译: `tag`。 。 。 .

#### `selectorFromTabOrderEntry(entry): string`

从 a 生成 CSS 选择器 `TabOrderEntry`优先级: `#id` > 翻译: `tag[role="..."]` > 翻译: `tag`。 。 。 .

#### `htmlSnippetFromFocusedElement(el): string`

从一个 `A11yFocusedElement`。 。 。 .

#### `htmlSnippetFromTabOrderEntry(entry): string`

从 a 生成一个 HTML 最小片段 `TabOrderEntry`。 。 。 .

## 类型

```typescript
import type {
  OracleIssue,         // Main issue object
  OracleNode,          // Axe-compatible node result
  OracleCheck,         // Individual check within a node
  OracleImpact,        // 'minor' | 'moderate' | 'serious' | 'critical'
  OracleResultType,    // 'violation' | 'incomplete' | 'oracle'
  OracleRule,          // Rule metadata
  AuditContext,        // { project, specName, wcagLevel?, disabledRules? }
  WcagLevel,           // 'wcag2a' | 'wcag2aa' | 'wcag21a' | 'wcag21aa' | 'wcag22a' | 'wcag22aa'
} from '@a11y-oracle/audit-formatter';
```

## 出口

```typescript
// Types
export type { OracleIssue, OracleNode, OracleCheck, OracleImpact, OracleResultType, OracleRule, AuditContext, WcagLevel };

// Rule definitions
export { RULES, RULE_IDS, getRule, matchesWcagLevel };

// Pure formatter functions
export { formatFocusIssues, formatTrapIssue, formatNameIssues, formatRoleIssues, formatTabIndexIssues, formatAllIssues };

// Selector utilities
export { selectorFromFocusedElement, selectorFromTabOrderEntry, htmlSnippetFromFocusedElement, htmlSnippetFromTabOrderEntry };

// Convenience class
export { OracleAuditor };
export type { OrchestratorLike };
```

## 常见问题

### @a11y-oracle/audit-formatter 是什么？

将访问结果转换为轴- 核心兼容 Oracle Isue 对象与 WCAG 规则元数据

### 如何安装 @a11y-oracle/audit-formatter？

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

### @a11y-oracle/audit-formatter 支持 TypeScript 吗？

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

### @a11y-oracle/audit-formatter 支持 ESM 还是 CommonJS？

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

### @a11y-oracle/audit-formatter 可以商用吗？

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

### @a11y-oracle/audit-formatter 的下载量有多少？

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

### @a11y-oracle/audit-formatter 还在维护吗？

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