image-alt-text

图像替代文本无障碍技能

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

创建、审查或审核任何包含图像的页面时，请应用这些规则。 仅当项目包含 <img> 元素、用作内容的内联 SVG 图像，或可能传达含义的 CSS 背景图像时，才加载此技能。

---

核心要求

WCAG 2.2 SC 1.1.1 非文本内容（A）：每个非文本元素都必须有实现等效用途的文本替代。装饰性图像也不例外——必须明确使用空的 alt=""。替代文本取决于图像在特定上下文中的用途，而非文件本身：同一资源在不同用途中可能需要不同的替代文本，也可能不需要替代文本。

切勿编造细节——不要根据外表猜测某人的身份、种族、族裔、性别、残障、诊断、宗教、年龄或情绪。自动化工具可以检测结构问题（缺少 alt）；只有人类判断才能确定替代文本是否有意义、准确且适合上下文。

---

严重程度分级（此技能）

级别	含义
严重	传达关键信息的图像没有 alt 属性，或完全缺少 alt
严重	功能性图像（按钮/链接）没有文本替代，导致无法使用键盘或屏幕阅读器
中等	存在替代文本，但内容不准确、重复（“……的图像”），或缺少有意义的上下文
轻微	替代文本略显冗长或有改进空间，但不影响理解

---

替代文本决策流程

对于图像的每种用法（而非笼统地针对资源本身），依次询问：

1. 图像是否是链接、按钮或控件中唯一用于命名的内容？ → 为操作或目标提供名称。
2. 图像是否包含在此处具有重要意义的文字？ 如果附近已有相同的文字内容，使用 alt=""；否则在替代文本中包含必要文字。
3. 图像是否增添信息、含义、身份、状态、说明或预期印象？ 简单图像 → 简洁的替代文本。复杂图像 → 简短说明图像内容，并提供无障碍的详细等效内容。
4. 图像的所有相关信息是否已在附近提供？ → alt=""。
5. 图像是否纯属装饰，或仅用于视觉排版？ → alt=""。
6. 仍不确定？ 发布前先弄清图像存在的原因——不要猜测。

WCAG 并未规定通用的字符数上限——应使用能传达必要用途的最简短替代文本，并将大量或结构化信息放入页面中可见的内容，而不是写成长篇 alt。

如果你在纠结图像是否属于装饰性图像，它很可能不是——不必要的替代文本代价很低；缺少替代文本则可能导致含义完全丢失。

---

严重：信息性图像

信息性图像传达了附近文字中尚未提供的含义。

<img src="quarterly-growth.png" alt="Bar chart showing 23% revenue growth in Q3 2024">


<img src="quarterly-growth.png" alt="Blue and green bar chart">
<img src="quarterly-growth.png" alt="quarterly-growth.png">
<img src="quarterly-growth.png" alt="image">

上下文会改变替代文本——同一资源可能需要不同的替代文本：

<img src="buddy.jpg" alt="Buddy, a golden retriever with a red collar">


<img src="buddy.jpg" alt="">


<img src="buddy.jpg" alt="Buddy waits beside his handler before crossing the street">

当外观本身就是信息时（艺术史、产品比较、设计评论），适合使用直观的视觉描述。

---

中等：装饰性和冗余图像

只有当图像纯属美观、未增添周围文字以外的信息，且移除后不会影响理解时，才属于真正的装饰性图像。

<img src="decorative-divider.png" alt="">
<svg aria-hidden="true" focusable="false">...</svg>


<img src="decorative-divider.png">

<img src="decorative-divider.png" alt="decorative">

对于 <img>，优先使用 alt=""，而非 role="presentation"。不要使用 aria-hidden="true" 隐藏提供信息或控件名称的图像。多余的描述并非无害——它会打断阅读顺序，让导航更费力。

---

严重：功能性图片

如果图片是链接或控件的唯一内容，就必须描述其操作或目标位置，而不是图标的形状。

<a href="/"><img src="acme-logo.svg" alt="Acme home"></a>


<a href="/reports/annual">
  <img src="report-cover.jpg" alt="">
  <span>2026 annual report</span>
</a>


<button type="button" aria-label="Close dialog">
  <img src="close.svg" alt="">
</button>


<input type="image" src="submit-order.png" alt="Submit order">

如果控件有可见文本标签，其可访问名称必须包含该可见文本（支持语音输入，这是 WCAG 2.5.3「名称中的标签」的要求）。尽可能使用带有真实文本的常规 <button>，而非 <input type="image">。

功能性图片的 alt 为空且没有其他可访问名称，会导致控件未被标记——严重问题。

---

中等：复杂图片

图表、示意图、地图和信息图需要包含两个部分：用于识别图片及其用途或主要结论的简短替代文本，以及可见的详细等效内容（描述、数据表、有序步骤），以保留数值、标签、单位、趋势、比较和关系。

<figure>
  <img src="revenue-trend.png"
       alt="Line chart showing revenue rising each quarter in 2025. Data table follows.">
  <figcaption>
    <p>Revenue increased from $1.2 million in Q1 to $2.1 million in Q4.</p>
    <table>
      <caption>Quarterly revenue for 2025</caption>
      <thead><tr><th scope="col">Quarter</th><th scope="col">Revenue</th></tr></thead>
      <tbody>
        <tr><th scope="row">Q1</th><td>$1.2 million</td></tr>
        <tr><th scope="row">Q4</th><td>$2.1 million</td></tr>
      </tbody>
    </table>
  </figcaption>
</figure>

优先使用所有人都能看到的描述，而不是只使用 aria-describedby——通过 aria-describedby 引用的内容通常会被作为单一描述呈现，可能会丢失标题、表格及其他结构。不要依赖已过时的 longdesc 属性。有关特定领域的指导，请参阅 skills/charts-graphs/SKILL.md 和 skills/maps/SKILL.md。

---

中等：文字图片

优先使用真实的 HTML 文本，而非文字图片（WCAG 1.4.5）——真实文本可以调整大小、重新排版、适应用户设置的颜色，也更容易准确翻译。

<img src="sale-banner.png" alt="Summer sale: 50% off through July 31">


<img src="sale-banner.png" alt="">
<p><strong>Summer sale:</strong> 50% off through July 31.</p>

对于包含大量文字的海报或扫描通知，请将全文作为页面上的可见内容，并用 alt 标识图片。根据 1.4.5，徽标属于必要的文字图片，但仍需要替代文本——通常是组织或产品名称；如果徽标是首页链接的唯一内容，则还应加上“首页”。

---

中等：图形与标题

<figcaption> 不能成为信息性 <img> 省略 alt 的理由。应有意选择两者的关系：如果标题已提供完整的等效内容，就使用 alt=""；如果图片提供了标题之外的信息，就让 alt 补充这些信息；如果标题只是标题、署名或评论，而非等效内容，图片仍需有自己的替代文本。不要在两者中重复同一句话。版权、许可或照片署名信息不要只放在 alt 中——应保持可见。

---

轻微：分组、响应式图片和图像映射

**分组：**当多张图片共同表达一个数值（例如星级评分）时，只提供一次组合后的数值，并将重复的单位标记为 alt="" 或 aria-hidden：

<img src="star-filled.png" alt="Rating: 4 out of 5 stars">
<img src="star-filled.png" alt="">
<img src="star-empty.png" alt="">

**响应式图片：**将 alt 放在 <picture> 内的备用 <img> 上，绝不要放在 <source> 上。每个响应式来源都必须传达大致相同的信息——如果艺术指导改变了图片的含义，同一个替代文本可能就不再准确。

**图像映射：**为 <img> 提供描述整体情境的替代文本，并为每个 <area> 提供描述其目标位置或操作的替代文本。

<img src="campus-map.png" alt="Campus buildings" usemap="#campus-buildings">
<map name="campus-buildings">
  <area shape="rect" coords="20,30,120,100" href="/library" alt="Central Library">
</map>

有关内联 SVG，请参阅 skills/svg/SKILL.md。对于 <canvas>，请提供等效的备用内容和可通过键盘操作的替代方案——单独使用 aria-label 无法替代复杂的 canvas 内容。

---

编写优质替代文本

1. 简洁但完整——简单图片的替代文本以约 125 个字符为宜；复杂图片则使用长描述
2. 描述内容和用途，而非外观——但如果媒介（照片／绘画／屏幕截图）会影响含义、来源或解读，则应注明
3. 语境至关重要——同一张图片在不同用途中可能需要不同的替代文本；应针对每种语境编写，而非每个素材只写一次
4. 不要以 “Image of”、“Picture of” 或 “Photo of” 开头，除非媒介本身很重要——并非在所有情况下都禁止使用这些措辞
5. 避免堆砌关键词、文件名以及 SEO／营销用语——替代文本是为用户服务的，而非搜索引擎
6. 包含图片中出现的重要文字
7. 仅当身份已知、相关且适合公开时，才使用人物姓名；仅当可见特征与用途相关时才加以描述——不要推断种族、残障、情绪或其他敏感属性
8. 使用页面所用的语言，并采用常规大小写和标点，以便语音合成和盲文输出清晰易懂

---

常见的不良替代文本模式

模式	严重程度	修正方法
信息性 <img> 缺少 alt	严重	提供等效的替代内容
装饰性 <img> 缺少 alt	较严重	使用 alt=""
将文件名或 CMS 注入的文本用作 alt	较严重	替换为根据语境编写的文本
通用占位文本（"image"、"photo"、"chart"、"alt"）	较严重	描述相关内容或用途
alt="decorative"／alt="spacer"	较严重	使用 alt=""
草稿占位文本（"TBD"、"TODO"、"null"、"undefined"）	较严重	在做出实际决定前禁止发布
媒介无关紧要时使用“图片类型”前缀（"Image of…"、"Photo of…"）	中等	直接描述内容
替代文本与相邻的 <figcaption> 完全重复	中等	使用 alt=""，或使其内容互为补充
人物肖像的替代文本仅包含姓名	中等	在相关且已知时补充角色／语境
使用 title 代替 alt	较严重	使用 alt；不要依赖仅悬停时显示的文本
给 <img> 添加 aria-label 而非 alt	中等	使用原生的 alt 属性
将完整图表数据塞进一段很长的 alt	中等	使用简短的替代文本 + 可见的结构化数据
在所有语境中重复使用同一条素材级替代文本	中等	针对每种用途编写替代文本
未经审核便发布 AI 生成的文本	较严重	要求由了解语境的人员审核通过

---

CSS 背景图片

CSS background-image 不支持 alt——仅用于装饰，或在等效信息已作为实际内容呈现时使用。

/* OK: decorative */
.hero { background-image: url('geometric-pattern.svg'); }

<div class="award-badge"></div>


<p class="award-badge">Winner, 2026 Inclusive Design Award</p>

用户样式、强制颜色、打印或内容拦截器可能会隐藏背景图片——页面不得依赖这些图片来呈现关键信息或功能。

---

CMS 和内容编写要求

内容系统应支持作者做出选择，而非只要求填写非空字段。应为作者提供必选项（信息性／功能性／装饰性或冗余／需要详细描述）、允许有意留空的替代文本字段，以及图片使用位置的语境信息。不要用文件名、说明文字或素材标题自动填充空的替代文本字段——说明文字、署名和替代文本用途各不相同。

以下情况应阻止发布： 尚未做出替代文本决定；信息性图片没有替代文本或等效的可见文本；功能性图片未说明其控件的功能；复杂图片缺少等效的详细描述；将占位文本／文件名用作替代文本。不要仅仅因为字段为空，就阻止有意设置的 alt=""——应要求作者确认该图片在当前用途中属于装饰性图片。

---

AI 辅助替代文本

AI 可以提供描述草稿建议，但无法可靠判断编辑目的、受众或冗余情况。AI 辅助工作流应当：询问与目的相符的文本，而非罗列视觉元素；区分信息性、功能性、装饰性和复杂用途；对不确定之处予以标注，而不是捏造细节；避免推断敏感属性或识别身份不明的人物；避免将私人图片或元数据发送到未经批准的服务；要求负责人在渲染后的上下文中审核建议；并将复杂图片交由人工撰写详细的等效描述。切勿让 AI 生成的信心取代编辑责任——流畅的描述仍可能不准确、有偏见或不安全。

---

自动化测试与人工测试

自动化工具可以检测	需要人工审核
缺少 alt 属性	替代文本是否有意义
功能性图片的 alt 为空	替代文本是否符合上下文
替代文本与文件名相同	装饰性图片是否确实不需要替代文本
可疑的前缀短语、已知占位符	描述是否传达了正确含义
替代文本与相邻的 figcaption 相同	应保留替代文本还是图注
图片按钮／图像映射区域缺少名称	复杂描述是否保留了各元素之间的关系

axe-core 等自动化工具可以检测结构问题；评估质量始终需要人工审核。将工具／规则版本与结果一并保存，并通过 skills/bug-reporting/SKILL.md 提交已确认的问题。

---

完成标准清单

• 每处图片使用都有明确的目的和替代文本决策
• 每个有意义的 <img> 都有准确且符合上下文的 alt
• 每个装饰性或完全冗余的 <img> 都有 alt=""
• 未将文件名、占位符、关键词列表或无关元数据用作 alt
• 功能性图片提供有用的链接或控件名称；可见标签包含在可访问名称中
• 仅在图片中显示的重要文字也以文本形式提供
• 复杂图片有简短的识别说明和可访问的详细等效描述
• 图注与替代文本相辅相成，而非重复彼此内容
• 响应式 <picture> 来源传达相同的核心含义；alt 位于回退用的 <img> 上
• CSS 背景图片不是信息或功能的唯一来源
• 替代文本使用页面语言，并纳入翻译工作流
• 描述不臆造身份、情绪或敏感属性
• AI 生成的建议经过了结合上下文的人工审核
• 已使用屏幕阅读器测试（NVDA + Firefox 或 VoiceOver + Safari）

---

关键 WCAG 标准

• 1.1.1 非文本内容（A）——任何有意义的图片缺少文本替代方案时均为严重问题
• 1.4.5 文字图片（AA）——优先使用真实文本，而非文字图片
• 1.4.9 文字图片，无例外（AAA）
• 2.4.4 链接目的（结合上下文）（A）——纯图片链接和组合链接必须传达其目的
• 2.5.3 标签在名称中（A）——可见的控件文本必须包含在可访问名称中
• 4.1.2 名称、角色、值（A）

---

参考资料

• 完整最佳实践指南
• W3C WAI——图片教程和决策树
• WCAG 2.2——1.1.1 非文本内容
• WebAIM——撰写有效的替代文本
• Sa11y——标记可疑的替代文本模式
• axe-core 规则：image-alt、image-redundant-alt、input-image-alt、area-alt、object-alt