# @a11y-oracle/axe-bridge 中文文档

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

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

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

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

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

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

## 中文简介

Axe-core结果后处理器,使用视觉分析,键盘交互和CDP检查来解决10个不完整的规则

## 安装

```sh
npm install @a11y-oracle/axe-bridge
```

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

## README

# @ a11y- oracle/ 轴桥

Axe-core结果后处理器,通过视觉分析,键盘交互,以及CDP检查来解决"不完全"(Needs Review)结果. 轴- 核心的中间软件 `analyze()` 还有你的主张.

## 问题

轴-核标记规则在需要状态变化,相互作用,或空间意识,静态DOM分析无法可靠地进行时被标记为"不完全". 这在CI仪表板中产生噪音,需要人工审查颜色对比,焦点指标,目标大小等规则.

## 解决办法

`resolveAllIncomplete()` 取得核心成果,并举行社区发展方案现场会议,然后通过10个专门解决者进行管道工作,促进从 `incomplete` 改为 `passes` 或者说 `violations`数字 :

| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 规则ID | WCAG 常设委员会 | 技术 |
| --- | --- | --- | --- |
| 1个 | `color-contrast` | 1.4.3 国家 | CSS 光环热学+像素级截图分析 |
| 2个 | `identical-links-same-purpose` | 2.4.4 (中文(简体) ) | URL 正常化和比较 |
| 3个 | `link-in-text-block` | 1.4.1 国家 | 默认状态计算样式检查 |
| 页:1 | `target-size` | 2.5.8 国家 | 边框测量+间距 |
| 页:1 | `scrollable-region-focusable` | 2.1.1 国家 | 滚动高度 + 可聚焦儿童转动 |
| 6个 | `skip-link` | 2.4.1 国家 | 标签焦点能见度验证 |
| 第7条 | `aria-hidden-focus` | 4.1.2 国家 | 全键盘 Tab 翻转 |
| 第8条 | `focus-indicator` | 2.4.7 国家 | 截图像素 diff 前后 |
| 第9条 | `content-on-hover` | 1.4.13 国家 | Hover + 排除交互测试 |
| 10个 | `frame-tested` | 不详 | 跨原产地iframe轴-核心注射 |

## 安装

```bash
npm install @a11y-oracle/axe-bridge
```

## 使用量

### 解决所有不完整(建议)

```typescript
import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';

// After running axe-core while the page is still live:
const axeResults = await axe.run(document);
const resolved = await resolveAllIncomplete(cdpSession, axeResults);

// resolved.incomplete will have fewer (or zero) entries
// resolved.violations and resolved.passes will have the promoted entries
```

### 有选项

```typescript
const resolved = await resolveAllIncomplete(cdpSession, axeResults, {
  wcagLevel: 'wcag22aa',
  contrast: {
    threshold: 4.5,              // normal text contrast ratio
    largeTextThreshold: 3.0,     // large text contrast ratio
    supermajorityPassRatio: 0.75, // auto-pass split decisions when 75%+ pixels pass
    bestCaseMultiplier: 2.0,     // auto-pass when best-case CR exceeds 2× threshold
  },
  focusIndicator: { focusSettleDelay: 150, diffThreshold: 0.2 },
  skipRules: ['frame-tested'], // skip specific resolvers
});
```

### 个人解决者

每个解析器可以单独使用:

```typescript
import { resolveIncompleteContrast } from '@a11y-oracle/axe-bridge';

const resolved = await resolveIncompleteContrast(cdpSession, axeResults, {
  wcagLevel: 'wcag22aa',
});
```

### 与剧作家

```typescript
import { test, expect } from '@playwright/test';
import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';

test('no unresolved accessibility issues', async ({ page }) => {
  await page.goto('/my-page.html');
  const cdp = await page.context().newCDPSession(page);

  const axeResults = await axe.run(document);
  const resolved = await resolveAllIncomplete(cdp, axeResults);

  expect(resolved.violations).toHaveLength(0);
  expect(resolved.incomplete).toHaveLength(0);

  await cdp.detach();
});
```

### 与赛普斯

```typescript
// Using Cypress.automation for CDP access:
cy.window().then(async (win) => {
  const axeResults = await axeCore.run(win.document);

  // cdpSession obtained via Cypress.automation('remote:debugger:protocol', ...)
  const resolved = await resolveAllIncomplete(cdpSession, axeResults);

  expect(resolved.violations).to.have.length(0);
});
```

## API 参考

### `resolveAllIncomplete(cdp, axeResults, options?)`

管子能按顺序通过所有10个溶液 每个解析器都收到上一个的输出.

-   **参数:**
    -   `cdp: CDPSessionLike` —— CDP会话连接到页面
    -   `axeResults: AxeResults` - 轴心核心的原始结果 `analyze()`
    -   `options?: IncompleteResolutionOptions` - 替代选择和 `skipRules` 过滤器
-   **回返情况:** `Promise<AxeResults>` ——经修改的附解结论的副本
-   **管道顺序 :** 相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相相通相通相通相通相通相通相通相通相通相通相通相通相通相相相通相通相通相相通相通相通相通相通相通相相相通相通相相相相相相相相相通相通相

### 个人解决者

#### `resolveIncompleteContrast(cdp, axeResults, options?)`

决定: `color-contrast` 使用 CSS 光电图和像素级截图分析的不完整条目. 已解决的节点(通过和违反)在轴检查中以对比数据来丰富 `data` 字段,包括 `contrastRatio`, (中文(简体) ), `expectedRatio`, (中文(简体) ), `fgColor`, (中文(简体) ), `bgColorLightest`, (中文(简体) ), `bgColorDarkest`,以及 `algorithm` (单位:千美元)`'visual-pixel'` 或者说 `'visual-halo'`) (中文(简体) ).

-   **选项 :** `ContrastResolutionOptions`数字 :
    -   `wcagLevel` - WCAG 合规级别(默认: `'wcag22aa'`。阈值是自动得出的(AA → 4.5/3.0)。 A级没有对应的SC,所以解析器被跳过.
    -   `threshold` 常规文本的最小对比比(覆盖) `wcagLevel`(中文(简体) )
    -   `largeTextThreshold` 大于大文本的最小对比率(覆盖) `wcagLevel`(中文(简体) )
    -   `supermajorityPassRatio` ——在分出决定(一个极端通过,一个失败)时,如果至少是这个像素通过的比例(默认: `0.75`(中文(简体) )
    -   `bestCaseMultiplier` ——在分拆裁定中,如果最佳案例对比率超过阈值乘以该值,则自动通过(默认: `2.0`(中文(简体) )
-   从轴-核的检查数据自动检测出大文本(QQ 24px或粗QQ 18.66px)

#### `resolveIdenticalLinksSamePurpose(cdp, axeResults)`

决定: `identical-links-same-purpose` 通过将 URL 正常化( 截取查询参数, 散列, 解析相对路径)并比较目的地 .

-   同一个目的地 **过**, 不同 ) **违反**

#### `resolveLinkInTextBlock(cdp, axeResults, options?)`

决定: `link-in-text-block` 通过检查 **默认/恢复状态** 非彩色视觉指示器.

-   **选项 :** `LinkInTextBlockOptions` —— 说 `linkTextContrastThreshold` (默认: 3.0)
-   检查 : `text-decoration: underline`, (中文(简体) ), `border-bottom > 0`, (中文(简体) ), `font-weight` 与父母的差别
-   如果没有非颜色指标: 比较链接与周围文本颜色对比

#### `resolveTargetSize(cdp, axeResults, options?)`

决定: `target-size` 通过测量边框和中枢间距.

-   **选项 :** `TargetSizeOptions` —— 说 `minSize` (默认:24)
-   宽度/高度 = 24px = **过**; 24px+相距小于 − **过**;否则—— **违反**

#### `resolveScrollableRegionFocusable(cdp, axeResults, options?)`

决定: `scrollable-region-focusable` 检查卷轴高度、标签索引和可聚焦儿童.

-   **选项 :** `ScrollableRegionOptions` —— 说 `maxChildren` (默认:50)
-   不实际可滚动 ~ **过**; 有过 `tabindex >= 0` → **过**;可聚焦儿童滚动到内容 ~ **过**

#### `resolveSkipLink(cdp, axeResults, options?)`

决定: `skip-link` 通过将跳过链接聚焦并验证它变得可见.

-   **选项 :** `SkipLinkOptions` —— 说 `focusSettleDelay` (默认:100)
-   检查边框、取景口封存、不透明、剪辑、位置

#### `resolveAriaHiddenFocus(cdp, axeResults, options?)`

决定: `aria-hidden-focus` 通过单一键盘 Tab 横跨所有被标记的节点.

-   **选项 :** `AriaHiddenFocusOptions` —— 说 `maxTabs` (默认:100)
-   标有标记的元素上的标签地- **违反**穿越完成,没有着陆 **过**

#### `resolveFocusIndicator(cdp, axeResults, options?)`

决定: `focus-indicator` 由焦点截取前后的像素分解. 元素被滚动到取景口后再被捕获,确保外屏元素产生有效的截图. 启用焦点模拟 `Emulation.setFocusEmulationEnabled` 因此焦点指标即使在无头浏览器或 Cypress AUT iframes 中也能产生.

-   **选项 :** `FocusIndicatorOptions` —— 说 `focusSettleDelay` (默认:100), `diffThreshold` (默认:0.1%)
-   截图完全相同 – **违反**; 像素已更改 ~ **过**

#### `resolveContentOnHover(cdp, axeResults, options?)`

决定: `content-on-hover` 与徘徊和解除交互测试.

-   **选项 :** `ContentOnHoverOptions` —— 说 `hoverDelay` (默认:300), `dismissDelay` (默认: 200)
-   测试: 内容出现在悬浮上, 当鼠标移动到内容( 可控) 时会留下, 在 Escape (可解除) 上消失

#### `resolveFrameTested(cdp, axeResults, options?)`

决定: `frame-tested` 通过CDP将轴心投入跨出源的iframes.

-   **选项 :** `FrameTestedOptions` —— 说 `axeSource` (完整的轴-核心脚本), `iframeTimeout` (默认: 3000)
-   用途 `Page.createIsolatedWorld` 绕过同源限制

### 管道公用事业

所有解析器使用的共享助手 :

```typescript
import {
  getSelector,        // Extract innermost CSS selector from axe node target
  cloneResults,       // Deep-clone AxeResults without mutation
  ruleShell,          // Create a rule shell (metadata only, no nodes)
  findIncompleteRule,  // Find a rule by ID in the incomplete array
  applyPromotions,    // Move nodes between incomplete/passes/violations
} from '@a11y-oracle/axe-bridge';
```

### 类型

```typescript
import type {
  // Axe-core compatible types
  AxeResults,
  AxeRule,
  AxeNode,
  AxeCheck,

  // WCAG level
  WcagLevel,
  ContrastThresholds,

  // Per-resolver options
  ContrastResolutionOptions,
  LinkInTextBlockOptions,
  TargetSizeOptions,
  ScrollableRegionOptions,
  SkipLinkOptions,
  AriaHiddenFocusOptions,
  FocusIndicatorOptions,
  ContentOnHoverOptions,
  FrameTestedOptions,

  // Orchestrator options
  IncompleteResolutionOptions,

  // Pipeline utility types
  PromotionResult,
} from '@a11y-oracle/axe-bridge';
```

> **说明:** Axe-core类型是本地定义的结构相容性而无需将轴-core作为运行时间依赖性.

## 如何运作

每个解析器都遵循一个共同的管道模式:

1.  **克隆** ——入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入出出出出出出出出出出出出入入入入入入入入入入入入入入入入入入入入入入入入入入入
2.  **查找** 目标规则在 `incomplete` 数组
3.  **分析** ——对于每个被标记的节点,运行解析器的具体技术(CDP查询,截图,键盘转盘等)
4.  **宣传** — 将已解析的节点移动到 `passes` 或者说 `violations`; 未解决的节点留在 `incomplete`

这个 `resolveAllIncomplete` 管弦乐团将所有解析器按顺序排列,因此发现结果通过管道积累.

## 依赖关系

-   **`@a11y-oracle/visual-engine`** ——视觉分析引擎(卤素检测,像素分析,PNG解码,CDP捕获)
-   **`@a11y-oracle/focus-analyzer`** — 颜色解析和对比比计算
-   **`@a11y-oracle/keyboard-engine`** – 本地 CDP 键盘调度用于跳转链接, aria- hidden- focus, 和内容- hover
-   **`@a11y-oracle/cdp-types`** —— 说 `CDPSessionLike` 用于框架不可知的 CDP 访问的界面

## 常见问题

### @a11y-oracle/axe-bridge 是什么？

Axe-core结果后处理器,使用视觉分析,键盘交互和CDP检查来解决10个不完整的规则

### 如何安装 @a11y-oracle/axe-bridge？

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

### @a11y-oracle/axe-bridge 支持 TypeScript 吗？

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

### @a11y-oracle/axe-bridge 支持 ESM 还是 CommonJS？

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

### @a11y-oracle/axe-bridge 可以商用吗？

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

### @a11y-oracle/axe-bridge 的下载量有多少？

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

### @a11y-oracle/axe-bridge 还在维护吗？

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