@ accesslint/ 核心

纯无障碍规则引擎,零浏览器依赖性. 包括具有最佳做法规则的WCAG 2.2 A级和AA级.

与AI编码代理? @accesslint/mcp 将此引擎包成模式背景协议服务器。 这个 Claude 代码插件 安装在一步.

找CI吗? 访问提示 对每个拉动请求进行无障碍检查,并直接在您的 GitHub PRs 上发布评论.

目录

• 为什么 @ accesslint/ core
• 安装
• 快开始
• API 密码
• 源头映射( 反应)
• 规则
• 兼容性
• 发展

为什么 @ accesslint/ core

• 同步 API —— 说 runAudit() 立即返回结果,不需要同步/等待
• 与快乐的境界合作 ——全力支持快乐度,jsdom,以及没有多填或工作环的正版浏览器,包括虚拟 DOMs 中的色彩对比检查
• 轻巧 - 46 KB gzipped(IIFE),零运行时间依赖性
• 中断审计 ——按时间编制预算的处理方式 createChunkedAudit 以避免主线条上的长任务
• 源头映射( 反应) ——选入 attachReactFiberSource 行走 React DevTools 纤维并解决被捆绑的通克 URL 通过其源图,因此违规指向真实源文件(src/Card.tsx:42:7) 而不是不透明的选择器
• 无害环境管理、CJS和IIFE – 树可摇动的 ES 模块,用于节点的 CommonJS 和用于脚本注入任意一页的单文件 IIFE

安装

npm install @accesslint/core

快开始

Vitest + 反应测试库

审计您现有测试套件中已实现的组件 :

import { render } from "@testing-library/react";
import { runAudit } from "@accesslint/core";
import { LoginForm } from "./LoginForm";

test("LoginForm has no accessibility violations", () => {
  const { container } = render(<LoginForm />);
  const { violations } = runAudit(container.ownerDocument);
  expect(violations).toEqual([]);
});

剧作家

将库输入页面并审计实时 DOM :

// a11y.spec.ts
import { test, expect } from "@playwright/test";

const iife = require.resolve("@accesslint/core/iife");

test("page has no accessibility violations", async ({ page }) => {
  await page.goto("https://example.com");

  await page.addScriptTag({ path: iife });

  const violations = await page.evaluate(() => {
    const { runAudit } = (window as any).AccessLint;
    return runAudit(document).violations.map((v: any) => ({
      ruleId: v.ruleId,
      message: v.message,
      selector: v.selector,
      impact: v.impact,
    }));
  });

  expect(violations).toEqual([]);
});

齐压

将库输入页面并审计实时 DOM :

// cypress/e2e/a11y.cy.js
Cypress.Commands.add("audit", () => {
  return cy.readFile("node_modules/@accesslint/core/dist/index.iife.js").then((src) => {
    return cy.window().then((win) => {
      win.eval(src);
      const result = win.AccessLint.runAudit(win.document);
      return result.violations;
    });
  });
});

describe("sample.html accessibility audit", () => {
  beforeEach(() => {
    cy.visit("sample.html");
  });

  it("has no accessibility violations", () => {
    cy.audit().should("have.length", 0);
  });
});

API 密码

runAudit(doc: Document, options?: AuditOptions): AuditResult

运行所有针对文件的有效规则并返回违反 。 所有选择都是按要求进行的,不重复——没有触及全球状况.

interface AuditOptions {
  additionalRules?: Rule[];
  disabledRules?: string[];
  includeAAA?: boolean;
  componentMode?: boolean;
  locale?: string;
}

interface AuditResult {
  url: string;
  timestamp: number;
  testEngine: TestEngine;
  testEnvironment: TestEnvironment;
  violations: Violation[];
  ruleCount: number;
  skippedRules: { ruleId: string; error: string }[];
}

interface TestEngine {
  name: "accesslint";
  version: string;
}

interface TestEnvironment {
  userAgent: string;
  windowWidth: number;
  windowHeight: number;
  orientationAngle: number;
  orientationType: string;
}

testEngine.version 这是 @accesslint/core 引擎版本. testEnvironment 描述已审计文档的域;不可读值返回到 "", (中文(简体) ), 0,以及 "portrait-primary"。 。 。 .

interface Violation {
  ruleId: string;
  selector: string;
  html: string;
  impact: "critical" | "serious" | "moderate" | "minor";
  message: string;
  context?: string;
  element?: Element;
  /** Source-code locations for the violating element, when populated by `attachReactFiberSource`. */
  source?: SourceLocation[];
}

interface SourceLocation {
  file: string;
  line: number;
  column?: number;
  /** Component or function name, when known (e.g. "ProductCard"). */
  symbol?: string;
  /** 0 = JSX literal that produced the element; 1+ = enclosing component(s). */
  ownerDepth: number;
}

version: string

引擎版本, 镜像 axe.version. 也作为 AccessLint.version 在独立的全球(IIFE)上.

import { version } from "@accesslint/core";

createChunkedAudit(doc: Document, options?: AuditOptions): ChunkedAudit

创建一个块式审计,在有时间框的批次中处理规则,以避免长的任务.

const audit = createChunkedAudit(document, { includeAAA: true });

function processNext() {
  const hasMore = audit.processChunk(16); // 16ms budget per frame
  if (hasMore) requestAnimationFrame(processNext);
  else console.log(audit.getViolations());
}

processNext();

rules

所有捆绑的阵列 Rule 对象.

getActiveRules(options?: AuditOptions): Rule[]

返回被给定选项过滤的捆绑规则:排除AAA级规则,除非 includeAAA 设置,在 componentMode ,不包括在 disabledRules附录 additionalRules时 locale 通过,返回带有翻译描述和指导的浅层规则.

getRuleById(id, options?: { locale?: string; additionalRules?: Rule[] }): Rule | undefined

查查身份证明 过 locale 获取翻译规则,或 additionalRules 还搜索自定义规则.

attachReactFiberSource(violations): Promise<void>

附加的页后处理器 source 每个地点 通过行走回放纤维来破坏 非反应页面上的禁用,生产建设, 或无纤维时,永不抛出。 要求联合来文X __source 转换 和 dev sourcemaps(默认在 CRA, Next dev, Vite + React 中).

当纤维携带 _debugSource 它被信任为现实; 否则 _debugStack (例如,Next.js dev)通过 块 .js.map。 。 。 .

限制 : 编辑 _debugSource 路径, dev 服务器 每个单元的序言(尤其是Vite,反应18和19)抵消所报告的 行/列——文件和组件保持正确,但行可以指向 比真源还低 这个 _debugStack 路径不受影响.

// In a Playwright test, after the audit:
const violations = await page.evaluate(async () => {
  const { runAudit, attachReactFiberSource } = (window as any).AccessLint;
  const result = runAudit(document);
  await attachReactFiberSource(result.violations);
  return result.violations;
});

console.log(violations[0].source);
// [{ file: "src/components/ProductCard.tsx", line: 42, column: 7, symbol: "ProductCard", ownerDepth: 0 }, ...]

公用事业

制定定制规则的助手:

• getAccessibleName(el) ——计算一个元素的可访问名称
• getComputedRole(el) 得到计算 ARIA 角色
• getImplicitRole(el) ——获得隐含(内在)ARIA角色
• isAriaHidden(el) ——检查元素是否通过 aria-hidden
• isValidRole(role) ——检查字符串是否是一个有效的 ARIA 角色
• getAccessibleTextContent(el) ——获得文本内容尊重 aria-hidden
• getSelector(el) ——为元素生成 CSS 选择器
• getHtmlSnippet(el) —— 获取元素的简略 HTML 片断

规则

包括WCAG 2.2 A级和AA级,外加最佳做法规则. 增加一个AAA级规则(distinguishable/color-contrast-enhanced捆绑但默认排除;通过 runAudit(doc, { includeAAA: true })。 。 。 .

规则 ID 匹配 ruleId 字段中的字段,并与 disabledRules 选项和 getRuleById()。 。 。 .

兼容性

在下列环境中试验:

发展

npm install
npm test        # 1191 tests
npm run bench   # performance benchmarks
npm run build   # produces dist/index.js, dist/index.cjs, dist/index.d.ts, dist/index.iife.js

找到窃听器还是有什么建议? 打开一个问题。 。 。 .

许可证

麻省理工学院