svg

SVG 无障碍技能

权威来源：mgifford/ACCESSIBILITY.md 中的 examples/SVG_ACCESSIBILITY_BEST_PRACTICES.md 此技能源自该文件。如有疑问，以示例为准。

创建、优化或审查 SVG 图形时，请遵循以下规则。 仅当项目包含 SVG 时，才加载此技能。

---

核心要求

SVG 的无障碍性取决于图形的用途和嵌入方式。装饰性图标、信息性图片、按钮内的图标和交互式图表需要采用不同的模式。首先确定用户需要从图形中获取什么，然后提供最简单的语义实现，以传达相同的信息或功能。仅添加 <title>、<desc>、role="img" 或 aria-label 并不能让 SVG 自动具备无障碍性——请在最终使用场景中测试效果。

SVG 也是一种可执行的 XML 格式，可能包含脚本、事件处理程序和外部资源引用。渲染不受信任的 SVG（上传内容、粘贴的标记、AI 生成的输出）之前，必须进行清理——请参阅下方的“安全”部分。

---

严重程度等级（本技能）

等级	含义
严重	SVG 传达了关键信息，却没有无障碍替代方案；或未经清理便渲染了不受信任的 SVG
高	SVG 可交互，但辅助技术用户无法访问或无法获取其标签
中	辅助技术体验有所下降，但内容仍能部分访问
低	未遵循最佳实践；影响轻微

---

根据用途和上下文选择模式

上下文	首选模式
使用 <img> 加载的装饰性 SVG	<img src="…" alt="">
使用 <img> 加载的有意义的 SVG	<img src="…" alt="Useful description">
装饰性内联 SVG	<svg aria-hidden="true">…</svg>
简单的有意义的内联 SVG	<svg role="img" aria-labelledby="…"><title>…</title></svg>
命名按钮或链接内的图标	为 HTML 控件命名，并隐藏 SVG
复杂图形	简短名称加上可见摘要、数据或详细描述
复用的精灵图标	为每个外层 <svg> 实例添加标签或隐藏它，而不是为共享的 symbol 添加标签
交互式图形	优先使用原生 HTML 控件；提供等效的结构化替代方案

优先使用原生 HTML 语义，而不是 ARIA。不要仅仅因为 <img> 的源文件是 SVG，就为其添加 role="img"——这是多余的。

---

重要：必须对辅助技术完全隐藏装饰性 SVG

<svg aria-hidden="true" focusable="false">
  
</svg>

aria-hidden="true" 会将 SVG 及其后代从无障碍树中移除——不要在以此方式隐藏的元素中放置可聚焦或可交互的内容。focusable="false" 用于解决旧版 IE／较早版本 Edge 中的行为问题；仍支持这些浏览器的项目可以保留此属性，但它并非适用于所有现代浏览器的通用要求。不要为有意隐藏的 SVG 添加 <title>／<desc>。绝不要用 role="presentation" 替代 aria-hidden="true"——在不同浏览器与屏幕阅读器的组合中，它无法可靠地阻止内容被朗读。

何时 SVG 属于装饰性内容？ 如果相邻的可见文本传达了相同含义，或者图片纯粹用于装饰，那么它就是装饰性的。如果移除它会导致用户缺少所需信息，那么它就是有意义的。

---

与 <img> 一起使用的外部 SVG

遵循与其他图片格式相同的文本替代规则。

<img src="/assets/images/service-area.svg" alt="Map showing the service area extending from Kingston to Ottawa" width="640" height="360">


<img src="/assets/images/flourish.svg" alt="" width="120" height="24">


<a href="/reports/annual-report.pdf">
  <img src="/assets/icons/download.svg" alt="Download annual report">
</a>

<img> 上的 role="img" 是多余的；如果 alt 可以提供名称，就不需要 aria-label。通过 <img> 加载时，内部 SVG 的 <title>／<desc> 不能替代 HTML alt——实际被朗读的是 HTML alt。

---

严重：简单且有意义的内联 SVG

<svg role="img" aria-labelledby="download-icon-title" viewBox="0 0 24 24">
  <title id="download-icon-title">Download</title>
  <path d="M12 3v12m0 0 5-5m-5 5-5-5M5 21h14"></path>
</svg>

<title> 必须是 <svg> 的直接子元素，并具有唯一 ID，通过 aria-labelledby 引用。当管理唯一标题 ID 会徒增复杂度时，使用纯 aria-label 是合理的替代方案：

<svg role="img" aria-label="Download" viewBox="0 0 24 24">…</svg>

除非有经过测试的特定理由，否则不要同时使用这两种模式——在计算可访问名称时，ARIA 标注属性的优先级高于 <title>（aria-labelledby > aria-label > 直接子元素 <title>）。注意：某些浏览器会将 <title> 显示为指针悬停提示——它不能替代可见文本或真正的可访问提示；键盘、触控或语音输入用户可能无法发现它。

---

严重：按钮和链接内的图标

HTML 控件应提供可访问名称——隐藏 SVG 图标。

<button type="button">
  <svg aria-hidden="true" viewBox="0 0 24 24"><path d="M6 6 18 18M18 6 6 18"></path></svg>
  Close
</button>


<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" viewBox="0 0 24 24"><path d="M6 6 18 18M18 6 6 18"></path></svg>
</button>

不要让按钮和其中隐藏的图标分别提供相同名称的不同版本——这会导致重复或不一致的播报。如果操作的含义可能不明显，优先使用可见标签——看似熟悉的图标在不同产品中可能有不同含义。

对于已标注按钮内通过 <img> 加载的外部 SVG 资源（例如主题选择器），使用 alt=""，因为按钮已提供名称——请注意，通过外部 <img> 加载的 SVG 不会继承周围按钮的 currentColor；请在该资源出现的每种背景上验证其自身颜色，或者如果必须让它遵循手动主题，则内联路径。

---

严重：可访问名称和描述——正确的 ARIA 关系

SVG 可访问名称的优先级：aria-labelledby > aria-label > 直接子元素 <title> > 其他回退方式。描述的优先级：aria-describedby > 直接子元素 <desc>。

<svg role="img" aria-labelledby="weather-title" aria-describedby="weather-desc" viewBox="0 0 320 180">
  <title id="weather-title">Weekly temperature trend</title>
  <desc id="weather-desc">Temperatures rise from 12 degrees Monday to 21 degrees Friday.</desc>
</svg>

确保整个 HTML 文档中的 ID 唯一——包含固定 SVG ID 的重复组件可能导致一个实例被另一个实例标注。不要将标题和描述的 ID 都放进 aria-labelledby——这会把两个字符串拼接成可访问的名称；使用 aria-labelledby 提供名称，并单独使用 aria-describedby 提供描述。不要将关键信息藏在 <desc> 中——辅助技术（AT）对长 SVG 描述的导航支持各不相同；请改为将关键信息放在可见的 HTML 中。

---

中等：复杂图形、示意图和图表

复杂 SVG 需要的不止一个冗长的可访问名称：简洁的名称、对用途或结论的可见摘要、必要时以结构化 HTML 呈现完整数据，以及在可交互时可通过键盘操作的控件。

<figure>
  <svg role="img" aria-labelledby="visitors-title" aria-describedby="visitors-summary" viewBox="0 0 640 360">
    <title id="visitors-title">Website visitors from January to March</title>
  </svg>
  <figcaption id="visitors-summary">
    Visitors increased each month, from 12,400 in January to 19,200 in March.
  </figcaption>
  <details>
    <summary>View the chart data</summary>
    <table>
      <caption>Monthly website visitors</caption>
      <thead><tr><th scope="col">Month</th><th scope="col">Visitors</th></tr></thead>
      <tbody><tr><th scope="row">January</th><td>12,400</td></tr></tbody>
    </table>
  </details>
</figure>

不要将详细表格重复放进 aria-label／<title>／<desc> 中——冗长的图像名称字符串难以浏览。ARIA Graphics Module 定义了结构化角色（graphics-document、graphics-object、graphics-symbol），但必须使用实际的 AT 组合进行测试；这些角色并不能取代等效的文本呈现。图表的具体要求请参见 skills/charts-graphs/SKILL.md。

---

复用图标和 SVG 精灵图

<svg aria-hidden="true" hidden>
  <symbol id="icon-download" viewBox="0 0 24 24">
    <path d="M12 3v12m0 0 5-5m-5 5-5-5M5 21h14"></path>
  </symbol>
</svg>
<button type="button">
  <svg aria-hidden="true" viewBox="0 0 24 24"><use href="#icon-download"></use></svg>
  Download report
</button>

共享符号中的名称很少适用于每个实例——“箭头”在不同语境中可能表示“下一步”“上一步”“展开”或“折叠”。应为控件或外层渲染实例命名，而不是为共享符号命名。外部 <use> 的目标必须引用一个实际且不同的元素（通常是带有 ID 的 <symbol>）——不要创建递归自引用。

---

中等：颜色、对比度和主题

.icon {
  fill: none;
  stroke: currentColor;
  stroke-linecap: round;
  stroke-width: 2;
}

currentColor 很有用，但并非强制要求——多色图形可能需要多个语义令牌；请在每种主题中验证每一组有意义的搭配。不要只依赖颜色——为状态/系列/选中状态添加文本标签、图案、线条样式或形状。SVG 内的文本也必须满足文本对比度要求；必要的图形信息通常需要达到 3:1；装饰性细节仅仅因为出现在有意义的图形中，并不需要达到 3:1。

@media (forced-colors: active) {
  .icon { color: ButtonText; }
  .chart-line { fill: none; stroke: CanvasText; }
  .chart-line[data-selected="true"] { stroke: Highlight; stroke-width: 4; }
}

不要不加区分地为每条路径同时设置 fill 和 stroke——这可能会把线条图变成实心形状。除非确有必要，并且已针对多种系统调色板进行测试，否则请避免使用 forced-color-adjust: none。

---

SVG 内的文本

保持重要标签清晰可见且易于辨认；满足文本对比度要求。不要仅仅为了保留字体而将重要标签转换为路径，也不要使用 font-size="0"、将文本定位在画布外或使用透明 SVG 文本来代替真正的文本替代方案。请在 HTML 中提供重要说明。测试缩放/放大效果——即使外层 SVG 可以缩放，SVG 标签仍可能重叠或被裁切。<foreignObject> 可以在 SVG 中嵌入 HTML，但会增加渲染/回退处理的复杂性——如果在 SVG 外使用普通 HTML 也能达到相同效果，请优先采用普通 HTML。

---

严重：交互式 SVG

优先在图形附近放置原生 HTML 按钮、链接和展开控件，而不是在 SVG 内部实现交互：

<div class="map">
  <svg aria-hidden="true" viewBox="0 0 640 360"></svg>
  <ul class="map-locations">
    <li><a href="/locations/ottawa">Ottawa service centre</a></li>
  </ul>
</div>

如果必须在 SVG 内进行交互：对于真正的导航，请使用 SVG <a href="…">；提供能描述用途的无障碍名称；保持合理的 DOM/焦点顺序；支持预期的键盘操作；显示清晰且不被裁切的焦点指示器；满足目标尺寸要求；公开选中/展开/按下状态；确保无障碍名称包含可见标签，以便语音输入使用；如果无法通过非视觉方式浏览视觉布局，请提供等效的 HTML 列表/表格。不要将每个数据点都加入 Tab 键顺序——数百个焦点停靠点会让可视化在技术上可访问，但在实际使用中无法操作。不要仅通过为 <path>/<g> 添加 tabindex="0" 和点击侦听器来创建“按钮”——这样既没有原生按钮语义，也不具备键盘操作行为。键盘无法访问的交互式 SVG 属于严重问题。

---

严重：动效、动画和闪烁

.loading-icon { transform-origin: center; }
@media (prefers-reduced-motion: no-preference) {
  .loading-icon { animation: spin 1s linear infinite; }
}

不要使用笼统的 svg * 规则来减少动效——这可能影响不相关的组件并覆盖有意义的状态。请针对特定的动画组件，并定义易于理解的静态状态：

@media (prefers-reduced-motion: reduce) {
  .diagram-panel { animation: none; transition: none; }
}

对于 <animate>/<animateTransform>，请使用 begin="indefinite"，并且仅在确认 prefers-reduced-motion: no-preference 时通过 beginElement() 触发。

如果 SVG 动画以 3 Hz 或更高频率闪烁（WCAG 2.3.1），则属于严重问题——即使遵循减少动态效果偏好，也不能免除此项要求；闪烁阈值始终适用。WCAG 2.2.2 要求对持续 5 秒或以上且并非必要的移动/闪烁/自动更新内容提供暂停/停止/隐藏控件。WCAG 2.3.3（交互触发的动画，AAA）要求用户能够停用非必要的交互触发动效——即使是 AA，遵循 prefers-reduced-motion 也是一种有效做法。

---

响应式 SVG 和缩放

保留 viewBox，确保图形缩放时不会裁切其内部坐标系——优化过程中移除它并非小问题，而是会破坏流式布局。

.responsive-diagram { display: block; max-inline-size: 100%; block-size: auto; }

请在 200%/400% 缩放比例和窄视口下进行测试——画布可缩放并不保证标签会重新排布或保持易读。对于密集的图表，可考虑为小屏幕提供简化视图，并在旁边附上 HTML 说明。切勿通过禁用页面缩放来弥补 SVG 布局缺乏灵活性。

---

独立 SVG 文档

在浏览器中直接打开的 SVG 是文档，而不是 <img>——应包含命名空间、语言和无障碍名称：

<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="diagram-title"
     viewBox="0 0 800 450" lang="en" xml:lang="en">
  <title id="diagram-title">Request approval workflow</title>
</svg>

如果独立文件较复杂，请在用户打开它的位置附近链接到等效的 HTML 描述。

---

关键：安全、净化与构建处理

SVG 是一种活跃的 XML 格式，可能包含脚本、事件处理程序、链接、外部资源、CSS、动画、滤镜，以及通过 <foreignObject> 嵌入的 HTML。**看起来像图像的文件不能自动视为惰性内容。**无障碍元数据必须在处理过程中保留，但绝不能以削弱安全边界为代价——应针对同一份最终产物进行安全性和无障碍检查。

处理前先确定 SVG 的信任级别：

来源	必需的处理方式
作者可控（仓库中经过审查的图标）	审查变更，限制构建工具，验证最终输出
从受控来源生成（Mermaid／图表渲染器）	将渲染器和配置视为依赖项；验证生成的 SVG
平台生成（托管的图表服务）	记录平台／渲染器版本；验证托管结果
不可信（上传内容、粘贴的标记、用户编辑内容、远程文件、AI 生成内容）	强制执行输入限制，安全解析，使用支持 SVG 的允许列表进行净化，并在显示或导出前验证

内联 SVG、<object>、<embed> 和独立文档的功能范围比 <img> 更广，因此需要更严格的审查——今天对 <img> 安全的 SVG，日后可能被他人下载、直接打开或以内联方式嵌入。不同嵌入上下文不存在一种通用的无障碍处理方式。

使用维护良好的 SVG 专用净化器／允许列表净化不可信 SVG（例如，使用经过审查的 SVG 配置文件的 DOMPurify）——通用 HTML 允许列表可能会移除必要的 SVG 功能，或允许不需要的功能。请勿：

• 在净化前使用 innerHTML 插入不可信 SVG
• 将格式良好的 XML 视为安全的 SVG
• 将 DOMParser、XMLSerializer、格式化工具或 SVGO 当作净化器
• 使用正则表达式净化 SVG
• 假设文件名、MIME 类型或成功显示图像预览就能证明其安全
• 在净化后使用不可信字符串修改标记

净化应移除／拒绝：<script> 和事件处理程序属性（onclick）；javascript: 和其他未经批准的 URL 方案；意外的外部 href／xlink:href；CSS／@import／url() 中的外部资源；除非明确需要，否则移除 <foreignObject>／嵌入式 HTML；未经批准的动画／交互元素；处理指令、DTD、外部实体。通常需要且可安全允许同一文档中的 #fragment 引用（<use href="#icon">、marker-end="url(#arrowhead)"），但必须验证每个允许的片段都指向同一份已净化文档中的允许元素；允许片段并不意味着允许任意外部 URL。

在服务器端处理 XML 时，应安全解析：禁用 DTD 处理和外部实体解析；阻止解析器访问网络／本地文件；除非明确需要且已做好安全防护，否则避免使用 XSLT／XInclude；设置输入／嵌套／实体限制；解析／净化失败时应默认拒绝。

限制资源消耗——即使不执行脚本，SVG 也可能耗尽 CPU／内存：限制输入／解压后的大小、元素／属性数量、路径复杂度、<use> 嵌套深度、滤镜复杂度、嵌入数据 URL 的大小以及渲染尺寸。拒绝递归引用和超出策略限制的内容。 优化时保留无障碍性 — 配置构建以保留 viewBox；在使用时保留 <title>/<desc>；保留 role/aria-*/语言属性； 保留被 ARIA、<use>、剪切路径、遮罩、滤镜、渐变引用的 ID； 保留语义化 <text>；保留焦点/主题/强制颜色/减少动态效果样式；保留公开的 精灵图 symbol ID。为重复的内联组件生成唯一 ID — 将所有副本合并为相同 ID 的 优化器会同时破坏渲染和无障碍名称。锁定优化器版本，并使用有代表性的测试样例 测试配置更改；采用彼此独立的可安全编辑和生产环境优化配置。

推荐的处理顺序：（1）应用输入/资源限制，（2）使用安全的 XML 设置进行解析， （3）使用已批准的配置文件清理不可信输入，（4）仅应用受控转换，（5）使用经过审核的 版本化配置进行优化，（6）验证最终 SVG 的安全性和无障碍性，（7）仅插入/提供/导出 通过验证的结果。如果后续任何步骤可能引入不可信标记，则在该步骤之后再次清理。

严格的 CSP 可以减轻某些不安全 SVG 特性的影响，但不能替代解析、清理、资源限制或 输出验证 — 应将其作为纵深防御，而非替代措施。

---

无需做的事项

• 不必为每个 SVG 添加 <desc> — 如果仅名称就能充分表达含义，则 <title> + aria-labelledby 已足够
• 非交互式 SVG 内不必添加焦点样式
• 如果 SVG 在没有该样式的情况下仍可感知，则不必添加 forced-colors 区块
• 装饰性 SVG 不必设置 role="img" — 应改用 aria-hidden="true"

---

测试

• 代码审查： 将每个 SVG 分类为装饰性/信息性/功能性/ 复杂/交互式；确认嵌入模式相匹配；检查名称/描述之间的关系；搜索重复的内联组件是否存在重复 ID；确认构建优化会保留必需属性；判定源内容的信任级别，并识别其可用于的所有嵌入场景； 审查清理器/解析器/优化器/渲染器配置的更改；确认最终输出验证同时涵盖安全性和无障碍性
• 浏览器/辅助技术： 检查无障碍树中的预期角色/名称/ 描述；确认装饰性图标不会被读出，命名图形只会被读出一次；仅使用键盘操作所有 SVG 控件；测试语音 输入名称是否与可见标签一致；测试 200%/400% 缩放和窄视口； 测试所有支持的主题；测试 prefers-reduced-motion/prefers-contrast/强制 颜色；确认含义不依赖颜色；如果 SVG 至关重要，则在图像不可用时进行测试
• 安全/处理： 保留有效和对抗性测试样例；测试完整流水线，而非仅孤立地测试清理器 — 拒绝脚本/事件处理程序；拒绝不安全的 URL 方案；阻止意外的外部资源；拒绝 DTD/外部实体，且不进行解析； 拒绝未经批准的 <foreignObject>；拒绝递归/过量的 <use>；拒绝过大/过于复杂的输入； 允许的同文档引用仍能正常渲染；重复的内联实例保留唯一 ID；优化后的输出仍符合安全规则，且与无障碍替代方案相符。每当清理器/解析器/优化器/渲染器/允许列表/依赖项 版本发生更改时，都要运行这些测试。

自动化工具可以检测缺失的 <img alt>、某些无障碍名称问题、重复 ID、对比度问题和某些 ARIA 错误 — 但无法判断替代方案是否等效、图形是否确实具有装饰性，或交互式可视化是否易于使用。任何自动化检查都不能替代人工 SVG 审查。

---

常见错误

错误	修正方法
<img src="graphic.svg"> 没有 alt	添加符合上下文的 alt；对于装饰性图片，使用 alt=""
每个 HTML <img> 都添加了 role="img"	使用原生 <img> 语义和 alt
在 aria-labelledby 中同时放入标题和描述 ID	使用 aria-labelledby 指定名称，使用 aria-describedby 指定描述
将长表格放在 <desc> 中	通过可见、有结构的 HTML 提供必要详情
重复的内联图标包含相同的标题 ID	为每个实例生成唯一 ID，或使用直接的 aria-label
精灵图符号引用自身	在符号中放入实际路径；仅从渲染实例引用
强制颜色 CSS 对每条路径都同时设置 fill 和 stroke	使用有针对性的系统颜色，不改变几何形状
可点击的 <path> 只有点击处理程序	使用原生 HTML 控件，或实现完整的键盘语义
使用 svg * 和 !important 实现减少动态效果	针对每个动态组件；定义有意义的静态状态
将格式正确的 XML 当作已清理的 SVG	安全地解析，并使用了解 SVG 的允许列表净化器
用正则表达式移除 <script> 后就称其为净化器	使用有文档化策略、经过维护且了解 SVG 的净化器
清理后的 SVG 随后又被不可信字符串修改	确保后续转换受控，或在最终验证前再次净化
将 CSP 当作净化的替代方案	仅将 CSP 用作额外防护层
因 SVG“看起来仍然正确”而接受优化器更新	锁定并测试优化器；验证语义、引用和替代内容

---

完成标准检查清单

• 已按用途（装饰性/信息性/功能性/复杂/交互式）和嵌入上下文对每个 SVG 分类
• 装饰性 SVG：aria-hidden="true" focusable="false"，不含 <title>、<desc>
• 有意义的 <img> SVG 具有实用的 alt；装饰性外部图片使用 alt=""
• 有意义的内联 SVG：role="img" + <title> + aria-labelledby（或 aria-label）
• 复杂 SVG：名称 + 可见摘要 + 结构化 HTML 详情
• 名称明确的控件中的图标不会重复控件的无障碍名称
• 名称/描述使用正确的 ARIA 关系（labelledby ≠ describedby）
• 优化过程中保留所有引用的 ID；重复实例之间 ID 唯一
• 在适当情况下使用 currentColor；非文本元素达到 3:1 对比度
• 存在并保留 viewBox
• 动态 SVG 仅在 prefers-reduced-motion: no-preference 时运行；无论偏好设置如何，都不得以 3 Hz 或更高频率闪烁
• 交互式 SVG 可通过键盘操作且具有可见焦点；优先使用原生包装元素
• 不可信 SVG 在插入任何 innerHTML 之前，必须使用了解 SVG 的允许列表进行净化
• 拒绝脚本、事件处理程序、不安全的 URL 方案、外部资源、DTD/实体
• 应用资源限制（大小、元素数量、<use> 深度、滤镜复杂度）
• 在最后一次实质性转换后运行安全和无障碍验证
• 已在受支持的操作系统/浏览器组合上使用屏幕阅读器进行测试

---

关键 WCAG 标准

• 1.1.1 非文本内容（A）— 有意义的 SVG 缺少文本替代时属严重问题
• 1.3.1 信息和关系（A）
• 1.4.1 颜色的使用（A）
• 1.4.3 对比度（最低）（AA）
• 1.4.5 文字图像（AA）
• 1.4.11 非文本对比度（AA）
• 2.1.1 键盘（A）
• 2.2.2 暂停、停止、隐藏（A）
• 2.3.1 三次闪烁或低于阈值（A）— 闪烁/频闪动画的严重问题
• 2.3.3 交互导致的动画（AAA）
• 2.5.3 标签中的名称（A）
• 2.5.8 目标尺寸（最低）（AA）
• 4.1.2 名称、角色、值（A）

---

参考资料

• 完整的最佳实践指南
• SVG 无障碍 API 映射
• WAI-ARIA 图形模块
• DOMPurify
• SVGO 文档
• OWASP XML 外部实体防护速查表
• WCAG 2.2 理解文档 1.4.11 非文本对比度
• MDN：prefers-reduced-motion

标准展望： WCAG 3.0 的 APCA 模型可能会调整非文本对比度的 3:1 比率。 目前仍适用 3:1 的要求。 请关注：https://www.w3.org/TR/wcag-3.0/