使用指南

使用 Speakable 分析 HTML 无障碍所需的一切，从安装到 CI/CD 集成。

安装

将其作为项目依赖安装以用于程序化调用和 CI 流水线，或全局安装以便在任意位置使用 CLI。

Terminal

# Install as a project dependency
npm install @reticular/speakable

# Or install globally for CLI access
npm install -g @reticular/speakable

CLI 命令

speakable 可执行文件接受 HTML 文件路径作为参数。所有选项均为标志，没有子命令。 For the full programmatic API with function signatures and parameters, see the API Reference.

Terminal

# Basic analysis (JSON output, NVDA by default)
speakable page.html

# Choose output format: json, text, audit, or both
speakable page.html -f text
speakable page.html -f json
speakable page.html -f audit
speakable page.html -f both

# Choose screen reader: nvda, jaws, voiceover, narrator, or all
speakable page.html -s nvda
speakable page.html -s jaws
speakable page.html -s voiceover
speakable page.html -s narrator
speakable page.html -s all

# Filter to specific elements with a CSS selector
speakable page.html --selector "button"

# Compare two HTML files (semantic diff)
speakable new.html --diff old.html

# Batch process multiple files
speakable --batch file1.html file2.html file3.html

# Write output to a file
speakable page.html -o output.json

# Read from stdin
cat page.html | speakable -

# Validate round-trip serialization
speakable page.html --validate

输出格式

Speakable 支持四种输出格式，分别适用于不同的工作流。

Format	Flag	Description
JSON	-f json	Canonical accessibility model as deterministic JSON. Best for CI/CD, snapshot testing, and programmatic comparison.
Text	-f text	Screen reader announcement text. Shows what each reader would say, line by line. Human-readable.
Audit	-f audit	Structured report with landmark structure, heading hierarchy, interactive elements, detected issues (error/warning/info), and summary statistics.
Both	-f both	JSON model and screen reader text combined in a single output.

Pro 功能

批量处理

在一次运行中分析多个文件。批量模式即使个别文件失败也会继续处理，并在结束时报告汇总结果。

speakable --batch file1.html file2.html file3.html

语义对比

对比修改前后的 HTML 以检测无障碍回归。对比会识别新增、删除和变更的节点，并给出属性级别的细节（名称、角色、状态、焦点）。 For deeper coverage of diff strategies, selectors, and snapshot testing workflows, explore the Advanced Guide.

speakable new.html --diff old.html

CI/CD 集成

利用退出码和 JSON 输出进行自动化流水线检查。退出码 0 = 成功，1 = 用户错误，2 = 内容问题或对比有变更，3 = 系统错误。 See CI/CD Integration for complete pipeline examples.

npx @reticular/speakable page.html -f audit

网页分析器

位于 /tool 的网页分析器让您可以直接粘贴 HTML 并即时查看结果，无需安装。

将您的 HTML 粘贴到文本框中
选择一款屏幕阅读器（NVDA、JAWS、VoiceOver、Narrator 或全部）
可选：输入 CSS 选择器以聚焦特定元素
点击“分析”查看预测输出

开启对比模式即可并排比较两段 HTML 片段。Speakable 会准确显示两个版本之间新增、删除或变更了哪些无障碍树节点。

分析后，点击输出工具栏中的 🔊 图标即可听取朗读结果，或切换到逐行模式，使用键盘快捷键逐条浏览输出。

语音播报器

网页分析器和浏览器扩展内置语音播报器，使用浏览器原生的 SpeechSynthesis API 朗读分析输出。

全部播放

依次朗读整段输出，行与行之间有停顿，屏幕阅读器各部分之间停顿更长。

逐行浏览

模拟屏幕阅读器用户的实际浏览方式：一次一个元素。

Key	Action
↓ / j	Move to next line and speak it
↑ / k	Move to previous line and speak it
Enter / Space	Play all from current line
Escape	Stop speech and exit line-by-line mode

语音与速度控制

语音下拉菜单包含语音选择器和从 0.5x 到 2.0x 的速度滑块。

最佳实践

Follow these recommendations to get the most value out of Speakable. For a checklist you can use before shipping, see the Testing Checklist.

在 CI 中运行以检测回归

将 Speakable 加入构建流水线，让每个 PR 都接受无障碍变更检查。

使用选择器进行组件级分析

使用 --selector 聚焦特定组件，而非分析整个页面。

检查全部四款阅读器

使用 -s all 查看跨平台差异。NVDA、JAWS、VoiceOver 和 Narrator 各有独特的播报模式。

保存 JSON 基线用于快照测试

将 JSON 输出保存为基线，然后使用 --diff 检测不同版本之间的变化。

从审计报告入手

使用 -f audit 快速概览无障碍健康状况，再深入研究特定阅读器的输出。

Advanced Guide

Deep dives into screen reader behavior, debugging workflows, and integration patterns.

Testing Checklist

Step-by-step checklist to verify accessibility before shipping your components.

Frameworks

Framework-specific integration guides for React, Vue, Angular, and more.

CI/CD Integration

Automate accessibility checks in your continuous integration pipeline.

安装