@ a11y- oracle/ 审计- formatter

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

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

安装

npm install @a11y-oracle/audit-formatter

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

使用量

纯格式函数

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

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);

甲骨文审计师类

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

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 片断 :

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规则:

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

关于每项规则的详细补救指导意见,见 补救指南。 。 。 .

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 类似接口

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。 。 。 .

类型

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';

出口

// 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 };