@a11y-oracle/视频引擎

可视像素分析引擎用于从轴-核心解析不完整的相色对比警告. 利用WCAG安全评估矩阵提供CSS光环高温检测,基于CDP的截图捕获和像素级发光分析.

安装

npm install @a11y-oracle/visual-engine

说明: 多数用户应使用 @a11y-oracle/axe-bridge 相反,它包住这个引擎,直接与轴-核心结果融合. 只有当您需要精细控制单个分析步骤或正在构建自定义集成时,才直接安装视觉引擎.

使用量

视觉连接分析器( 建议)

协调员班负责一个单一要素的整个管道:

import { VisualContrastAnalyzer } from '@a11y-oracle/visual-engine';
import type { CDPSessionLike } from '@a11y-oracle/cdp-types';

const analyzer = new VisualContrastAnalyzer(cdpSession);

const result = await analyzer.analyzeElement('#hero-text', 4.5);

switch (result.category) {
  case 'pass':       // Worst-case contrast passes threshold
  case 'violation':  // Best-case contrast fails threshold
  case 'incomplete': // Split decision, dynamic content, or unresolvable
}

单个管道步骤

管道的每个阶段也出口供后期使用:

import {
  getElementStyles,
  captureElementBackground,
  analyzeHalo,
  extractPixelLuminance,
} from '@a11y-oracle/visual-engine';

// 1. Get computed styles via CDP
const styles = await getElementStyles(cdp, '#my-element');

// 2. CSS halo fast path (no screenshot needed)
const halo = analyzeHalo(styles, 4.5);
if (halo.hasValidHalo) {
  // Element has a valid text stroke or shadow halo
}

// 3. Capture background with text hidden
const capture = await captureElementBackground(cdp, '#my-element');

// 4. Pixel-level luminance analysis
const pixels = extractPixelLuminance(capture.pngBuffer, capture.textColor);

分析管道

这个 VisualContrastAnalyzer.analyzeElement() 方法运行此管道 :

1. 获取计算样式 - 获取 color, (中文(简体) ), backgroundColor, (中文(简体) ), textStrokeWidth, (中文(简体) ), textStrokeColor, (中文(简体) ), textShadow,以及 backgroundImage 通过CDP Runtime.evaluate。 。 。 .

2. 动态内容检查 探测到视频/扫描器祖先、分一不透明以及CSS混合模式。 动态内容留作 incomplete。 。 。 .

3. CSS 光环光环 (快速路径)——检查:

   • -webkit-text-stroke 1px 与背景对比足够
   • text-shadow 4+ 零蓝度方向阴影覆盖所有二次曲线

   如果找到有效的光环,并且其颜色从背景上越过了阈值,则元素通过时没有截图.

4. 截图抓取 ——将元素卷入取景口(确保去屏幕元素产生有效的截图),隐藏元素的文本(集) color: transparent),通过 CDP 捕获被剪辑的截图 Page.captureScreenshot,然后恢复文本.

5. 像素分析 ——解码PNG,扫描出所有不透明的像素来表示亮度极端(最轻最暗),并计算出与文本颜色的对比比.

6. 安全评估矩阵数字 :

   • 过: 文本与 最轻 和 阴暗 背景像素都符合阈值(最糟糕的大小写通过)
   • 违反: 文本与 最轻 和 阴暗 背景像素都失败了阈值( 最好的情况失败)
   • 不完整: 一次通过,一次失败(分裂决定)——不能安全分类

API 参考

视觉连接分析器

constructor(cdp: CDPSessionLike)

创建绑定到 CDP 会话的分析器 .

analyzeElement(selector, threshold?): Promise<ContrastAnalysisResult>

运行整个管道在一个元素上.

• 选择器 ——针对元素的CSS选择器
• 阈值 最低对比率(默认:4.5)
• 回返 —— 说 ContrastAnalysisResult 与 category, (中文(简体) ), textColor, (中文(简体) ), halo, (中文(简体) ), pixels,以及 reason

光环检测

analyzeHalo(styles, threshold?): HaloResult

检查计算样式是否包含有效的 CSS 光环 .

• 样式 —— 说 ElementComputedStyles 从 getElementStyles()
• 阈值 最低对比率(默认:4.5)
• 回返 —— 说 HaloResult 与 hasValidHalo, (中文(简体) ), haloContrast, (中文(简体) ), method,以及 skipReason

parseTextShadow(css): TextShadowPart[]

分析 CSS text-shadow 值为结构部件.

像素分析

extractPixelLuminance(pngBuffer, textColor): PixelAnalysisResult | null

解码 PNG 并计算文本颜色的对比率.

• 缓冲 ——原始PNG缓冲器 captureElementBackground()
• 文本颜色 —— 说 RGBColor 预览文本
• 回返 显著的极端和对比比率,或 null 如果没有不透明的像素

decodePng(buffer): { width, height, data: Uint8Array }

将 PNG 缓冲解码为原始 RGBA 像素数据 .

截图抓取

getElementStyles(cdp, selector): Promise<ElementComputedStyles | null>

通过 CDP 获取元素的计算样式 .

captureElementBackground(cdp, selector): Promise<{ pngBuffer: Buffer; textColor: RGBColor | null } | null>

抓取一个元素的剪接截图, 并隐藏其文本 。 在抓取前自动将元素滚动到视图端口,确保折叠下方的元素产生有效的截图而不是空白图像.

类型

import type {
  ContrastAnalysisResult,  // Full analysis result
  ContrastCategory,        // 'pass' | 'violation' | 'incomplete'
  HaloResult,              // CSS halo analysis result
  PixelAnalysisResult,     // Luminance extremes + contrast ratios
  TextShadowPart,          // Parsed text-shadow entry
  ElementComputedStyles,   // Computed CSS properties for contrast analysis
} from '@a11y-oracle/visual-engine';

依赖关系

• @a11y-oracle/focus-analyzer - 重复使用 relativeLuminance(), (中文(简体) ), contrastRatio(),以及 parseColor() wCAG 色彩数学
• @a11y-oracle/cdp-types —— 说 CDPSessionLike 用于框架不可知的 CDP 访问的界面
• fast-png ——纯TypeScript PNG解码器/编码器(浏览器+节点.js兼容,没有本土依赖)