# @a11y-oracle/visual-engine 中文文档

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

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

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

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

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

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

## 中文简介

使用 CDP 截图抓取和亮度分析进行色彩对比分辨率的可视像素分析引擎

## 安装

```sh
npm install @a11y-oracle/visual-engine
```

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

## README

# @a11y-oracle/视频引擎

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

## 安装

```bash
npm install @a11y-oracle/visual-engine
```

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

## 使用量

### 视觉连接分析器( 建议)

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

```typescript
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
}
```

### 单个管道步骤

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

```typescript
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>`

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

## 类型

```typescript
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兼容,没有本土依赖)

## 常见问题

### @a11y-oracle/visual-engine 是什么？

使用 CDP 截图抓取和亮度分析进行色彩对比分辨率的可视像素分析引擎

### 如何安装 @a11y-oracle/visual-engine？

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

### @a11y-oracle/visual-engine 支持 TypeScript 吗？

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

### @a11y-oracle/visual-engine 支持 ESM 还是 CommonJS？

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

### @a11y-oracle/visual-engine 可以商用吗？

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

### @a11y-oracle/visual-engine 的下载量有多少？

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

### @a11y-oracle/visual-engine 还在维护吗？

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