htmlhint 默认输出不满足全局可用性需求，因其终端文本流缺乏WCAG准则映射、严重等级、DOM上下文及浏览器/屏幕阅读器实测表现，仅含文件路径、行号、列号和简短消息，无法支撑跨职能协作。
htmlhint 是当前最轻量、最易集成的 HTML 质量校验工具，但直接用它构建「全局可用性为中心」的可视化平台，不能只靠配置文件或命令行输出。
为什么 htmlhint 的默认输出不满足「全局可用性」需求
htmlhint 默认输出是终端文本流，每条规则报错只含文件路径、行号、列号和简短消息，比如：
index.html:12:5: Attribute 'alt' is required
这类信息对开发者调试有效，但对「全局可用性」——即面向产品、设计、无障碍专员、测试甚至法务人员的跨职能协作——完全不可读。没人会去数第 12 行第 5 列；更没人能凭“Attribute 'alt' is required”判断是否影响 WCAG 2.1 AA 合规。
- 报错缺乏上下文快照（对应 DOM 片段、渲染效果示意）
- 无严重等级映射（阻断性 / 建议性 / 法规强依赖）
- 不关联 WCAG 准则编号（如 1.1.1、4.1.2）
- 不区分浏览器/屏幕阅读器实测表现（仅静态分析）
如何把 htmlhint 输出转成可用性导向的可视化数据
核心不是重写校验器，而是做三层转换：
立即学习“前端免费学习笔记（深入）”；
- 第一层：将
htmlhint的 JSON 输出（启用--format json）解析为结构化错误对象 - 第二层：为每个 ruleId 注入元信息映射表，例如：
-
"alt-require"→ { wcag: "1.1.1", impact: "critical", description: "图像缺少替代文本，屏幕阅读器无法传达内容" } -
"html-lang-require"→ { wcag: "3.1.1", impact: "high", description: "页面未声明语言，影响语音合成器发音和翻译准确性" }
-
- 第三层：前端用这些 enriched error 对象渲染可交互视图，支持按 WCAG 准则、影响等级、DOM 节点类型（
img、button、form）筛选
关键点：不要在浏览器里重新跑 htmlhint，而是在 CI 流程中生成带元信息的 report.json，由可视化平台加载并渲染。
避免在可视化层重复实现语义检查逻辑
很多团队试图用 Puppeteer + axe-core 在可视化平台里“再跑一遍检测”，结果导致：
- 与开发阶段使用的
htmlhint规则不一致（axe 检查的是运行时 DOM，htmlhint检查的是源码） - 无法定位原始 HTML 行号（Puppeteer 截图里的节点找不到对应 .html 文件坐标）
- 性能差，每次加载都要重跑，无法缓存历史趋势
正确做法是：
- 所有规则校验统一在 pre-commit 或 CI 阶段用
htmlhint完成 - 可视化平台只做「呈现增强」，不参与「判断增强」
- 若需运行时验证（如 JS 动态插入的
img），单独走 axe-core pipeline，输出另存为runtime-report.json，与静态报告分开展示
.htmlhintrc 配置必须关闭的三项默认规则
以下规则看似合理，但在「全局可用性平台」语境下会产生大量噪声，干扰真正影响用户的缺陷：
-
"attr-lowercase"：属性名大小写属于风格问题，与可用性零相关 -
"tagname-lowercase"：HTML5 不区分标签大小写，强制小写对屏幕阅读器无任何影响 -
"id-unique"：ID 冲突是 JS 逻辑隐患，不是可用性问题（除非被aria-labelledby引用，那应单独建 rule）
保留且优先强化的规则应只聚焦于 WCAG 映射项："alt-require"、"html-lang-require"、"title-require"、"label-require"、"role-required-aria"
真正的可用性瓶颈从来不在格式规范，而在语义缺失和上下文断裂。
