# @code-pushup/axe-plugin 中文文档

规范地址：https://npmcn.com/package/%40code-pushup/axe-plugin/

版本：0\.126\.4
npm 元数据更新时间：2026-09-11T10:13:32.286Z
中文译文更新时间：2026-11-10T06:36:46.539Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40code-pushup/axe-plugin
原文对照：https://npmcn.com/package/%40code-pushup/axe-plugin/?lang=original
项目主页：https://github.com/code-pushup/cli/tree/main/packages/plugin-axe#readme
源码仓库：https://github.com/code-pushup/cli

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

- 包体积（解压后）：80.3 kB，47 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2025-11-12T14:57:24.785Z
- 最新版本发布：2026-09-11T10:13:31.969Z
- 近 30 天下载量：2844（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

代码 PushUp 插件, 用于使用 Axe 检测无障碍问题

## 安装

```sh
npm install @code-pushup/axe-plugin
```

也可以使用：`pnpm add @code-pushup/axe-plugin`、`yarn add @code-pushup/axe-plugin`、`bun add @code-pushup/axe-plugin`

## README

# @ code- pushup/ axe- 插件

[![npm](https://img.shields.io/npm/v/%40code-pushup%2Faxe-plugin.svg)](https://www.npmjs.com/package/@code-pushup/axe-plugin) [![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Faxe-plugin)](https://npmtrends.com/@code-pushup/axe-plugin) [![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/axe-plugin)](https://www.npmjs.com/package/@code-pushup/axe-plugin?activeTab=dependencies)

🕵️ **用Axe进行自动化无障碍测试的代码PushUp插件.** 🌐

* * *

该插件使用 [轴核](https://github.com/dequelabs/axe-core) 通过 Playwright. 它确定 [西非咨询组](https://www.w3.org/WAI/standards-guidelines/wcag/) 最佳做法建议 **100+无障碍度量衡** 详细指导解决问题.

**为什么无障碍测试很重要:** 这个 [欧洲无障碍法(EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) 要求欧盟的数字产品和服务达到与《网络内容无障碍准则》紧密相通的无障碍标准。 这个插件提供全面的自动化测试,以帮助满足合规要求并积累包容性的经验.

## 开始

1.  如果还没有安装 [@ code- pushup/ cli (英语)](https://npmcn.com/package/%40code-pushup/cli/README.md) 并创建配置文件.
    
2.  用您的软件包管理器安装为 dev 依赖 :
    
    ```sh
    npm install --save-dev @code-pushup/axe-plugin
    ```
    
    ```sh
    yarn add --dev @code-pushup/axe-plugin
    ```
    
    ```sh
    pnpm add --save-dev @code-pushup/axe-plugin
    ```
    
3.  将此插件添加到 `plugins` 在代码 PushUp CLI 配置文件中的数组(例如 . `code-pushup.config.ts`) (中文(简体) ).
    
    通过您要测试的 URL :
    
    ```ts
    import axePlugin from '@code-pushup/axe-plugin';
    
    export default {
      // ...
      plugins: [
        // ...
        axePlugin('https://example.com'),
      ],
    };
    ```
    
    默认情况下,插件运行 **2.1 AA级** 审计。 您可以使用 [预设](https://npmcn.com/package/%40code-pushup/axe-plugin/#readme-presets)。 。 。 .
    
4.  用 CLI 运行 CLI `npx code-pushup collect` 并查看或上传报告(参见 [CLI 文档](https://npmcn.com/package/%40code-pushup/cli/README.md)) (中文(简体) ).
    
    > **说明:** 该插件使用Playwright在Chrimium运行测试. 浏览器如果尚未安装, 将自动安装 .
    

## 配置

```ts
axePlugin(urls: PluginUrls, options?: AxePluginOptions)
```

**参数:**

-   `urls` - 要测试的 URL。 见 [多个 URL](https://npmcn.com/package/%40code-pushup/axe-plugin/#readme-multiple-urls) 或 [`PluginUrls`](https://npmcn.com/package/packages/models/docs/models-reference.md#pluginurls) 参考文献
-   `options` - 可选配置对象

**选项 :**

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `preset` | `AxePreset` | `'wcag21aa'` | 无障碍规则预设 |
| `setupScript` | `string` | `undefined` | 认证设置脚本的路径 |
| `scoreTargets` | `object` | `undefined` | 审计或组别通过/失效门槛值 |

见 [预设](https://npmcn.com/package/%40code-pushup/axe-plugin/#readme-presets) 财务报告和审定财务报表 [认证](https://npmcn.com/package/%40code-pushup/axe-plugin/#readme-authentication) 下节.

## 多个 URL

该插件支持测试单个或多个 URL :

```ts
// Single URL (string)
axePlugin('https://example.com');

// Multiple URLs (array)
axePlugin(['https://example.com', 'https://example.com/about']);

// Weighted URLs (record)
axePlugin({
  'https://example.com': 3, // homepage has 3x weight
  'https://example.com/about': 1, // about page has 1x weight
});
```

权重较高的URL对总体分数的贡献更大. 例如,有重3的URL具有有重1的URL的三倍影响.

## 认证

要测试登录保护的页面,请提供 `setupScript` 分析前的认证:

```ts
axePlugin('https://example.com/dashboard', {
  setupScript: './axe-setup.ts',
});
```

设置脚本必须导出接收 Playwright 的默认async 函数 `Page` 实例:

```ts
// axe-setup.ts
import type { Page } from 'playwright-core';

export default async function (page: Page): Promise<void> {
  await page.goto('https://example.com/login');
  await page.fill('#username', process.env.USERNAME);
  await page.fill('#password', process.env.PASSWORD);
  await page.click('button[type="submit"]');
  await page.waitForURL('**/dashboard');
}
```

脚本在分析 URL 之前运行过一次. 认证状态(cookies, localStorage)在所有 URL 分析中自动共享.

选项: 基于 Cookie 的认证

如果您有会话符号, 您可以直接通过 cookie 注入 :

```ts
// axe-setup.ts
import type { Page } from 'playwright-core';

export default async function (page: Page): Promise<void> {
  await page.context().addCookies([
    {
      name: 'session_token',
      value: process.env.SESSION_TOKEN,
      domain: 'example.com',
      path: '/',
    },
  ]);
}
```

## 预设

选择用于测试的可访问性规则 `preset` 选项 :

```ts
axePlugin('https://example.com', {
  preset: 'wcag22aa',
});
```

可用的预设 :

| 预设 | 说明 | 使用大小写 |
| --- | --- | --- |
| `wcag21aa` | **2.1 A级和AA级** (默认) | 标准网络无障碍规定 |
| `wcag22aa` | **WCAG 2.2 A级和AA级** | 最新WCAG标准 |
| `best-practice` | **最佳做法** (非世界妇女咨询组的建议) | Deque的补充建议 |
| `all` | **所有可用规则** | 综合测试 |

### 预设细节

**`wcag21aa`** (默认)

-   测试遵守情况 [2.1 A级和AA级](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_overview&levels=a%2Caaa)
-   所需经费 [欧洲无障碍法(EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) 遵守情况
-   封面基本内容:键盘导航,相色对比,形式标签,备选案文等.

**`wcag22aa`**

-   测试遵守情况 [WCAG 2.2 A级和AA级](https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=a%2Caaa)
-   包括所有WCAG 2.1规则和新的成功标准
-   为即将出台的条例提供未来保护

**`best-practice`**

-   Deque Systems的非WCAG建议
-   超越法律要求
-   有助于创造更具包容性的经验

**`all`**

-   运行轴核中可用的每个规则
-   包括WCAG 2.0、2.1、2.2、实验规则和最佳做法
-   最全面的测试

> **说明:** 不同的页面可能会根据内容触发不同的套规则. 例如,没有视频的一页不会进行视频相关审计.

### 组

该插件根据轴-核心的可访问性类别将审计组织成类别:

-   `aria` -亚里雅
-   `color` - 颜色对比度( C)
-   `forms` - 表单
-   `keyboard` - 键盘
-   `language` - 语言
-   `name-role-value` - 名称和标签
-   `parsing` - 剖析
-   `semantics` - 语义学
-   `sensory-and-visual-cues` - 视觉库斯
-   `structure` - 结构
-   `tables` - 表单
-   `text-alternatives` - 替代文本
-   `time-and-media` - 媒体

使用 `npx code-pushup print-config --onlyPlugins=axe` 为您的配置列出所有审计和组.

## 类别整合

该插件提供了帮助将 Axe 结果整合到您的分类中 .

### 配备参考助手的建筑类别

使用 `axeGroupRefs` 财务报告和审定财务报表 `axeAuditRefs` 用于构建类别。 这些帮助者自动处理多URL扩展 :

```ts
import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin('https://example.com');

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: axeGroupRefs(axe),
    },
  ],
};
```

对于多URL设置,每个URL的参考器会自动扩展,并附带适当的权重:

```ts
import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin({
  'https://example.com': 2,
  'https://example.com/about': 1,
});

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: axeGroupRefs(axe),
    },
  ],
};
```

### 自定义带有特定组的类别

对于精细控制,请指定哪些组包括:

```ts
import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin('https://example.com');

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: [...axeGroupRefs(axe, 'aria', 2), ...axeGroupRefs(axe, 'color'), ...axeGroupRefs(axe, 'keyboard')],
    },
  ],
};
```

### 与灯塔结合

为全面无障碍测试,将Axe和Lighthouse的无障碍组合并成一个单一类别:

```ts
import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';
import lighthousePlugin, { lighthouseGroupRefs } from '@code-pushup/lighthouse-plugin';

const urls = ['https://example.com', 'https://example.com/about'];
const axe = axePlugin(urls);
const lighthouse = await lighthousePlugin(urls);

export default {
  plugins: [axe, lighthouse],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: [...lighthouseGroupRefs(lighthouse, 'accessibility'), ...axeGroupRefs(axe)],
    },
  ],
};
```

这给了你们两个灯塔的注重性能的无障碍审计和Axe的WCAG全面覆盖一个类别分数.

### 辅助功能

| 函数 | 说明 |
| --- | --- |
| `axeGroupRefs` | 创建 Axe 组的类别 refs, 处理多URL |
| `axeAuditRefs` | 创建 Axe 审计的类别 refs, 处理多URL |

> \[TIP\] 重量决定每个裁判对类别分数的影响. 使用重量 `0` 在不影响分数的情况下,只将一个参考者列为信息.

### 类型安全

这个 `AxeGroupSlug` 类型导出以发现有效的组 satters :

```ts
import type { AxeGroupSlug } from '@code-pushup/axe-plugin';

const group: AxeGroupSlug = 'aria';
```

### 贬值的帮助者

下列帮助者被贬值,并将在未来版本被删除:

| 函数 | 替换 |
| --- | --- |
| `axeCategories` | 手动构建分类 `axeGroupRefs` |
| `axeGroupRef` | 使用 `axeGroupRefs` 多URL支助(平面) |
| `axeAuditRef` | 使用 `axeAuditRefs` 多URL支助(平面) |

## 资源

-   **[轴心规则](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)** - 无障碍规则完整清单
-   **[德克大学](https://dequeuniversity.com/rules/axe/)** 详细解释和补救指南
-   **[WCAG 准则](https://www.w3.org/WAI/standards-guidelines/wcag/)** - 网络内容无障碍准则

## 常见问题

### @code-pushup/axe-plugin 是什么？

代码 PushUp 插件, 用于使用 Axe 检测无障碍问题

### 如何安装 @code-pushup/axe-plugin？

在项目目录运行 npm install @code-pushup/axe-plugin，或使用 pnpm add / yarn add / bun add。

### @code-pushup/axe-plugin 支持 TypeScript 吗？

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

### @code-pushup/axe-plugin 支持 ESM 还是 CommonJS？

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

### @code-pushup/axe-plugin 可以商用吗？

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

### @code-pushup/axe-plugin 的下载量有多少？

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

### @code-pushup/axe-plugin 还在维护吗？

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