如何为 HTML 卡片中包含图片或视频的 header 设置无障碍名称？

2026-11-04技术老齐

结论

示例中的 <header> 不需要单独设置无障碍名称。应删除它和 <footer> 上的 aria-labelledby，为其中的内容分别设置合适的标记：

图片使用 alt，装饰性图片使用 alt=""。
嵌入视频的 <iframe> 使用能说明视频内容的 title。
链接使用清楚的链接文字。
卡片整体需要名称时，可以保留 <section aria-labelledby="卡片标题的ID">。

容器名称不能代替图片的替代文本，也不能代替 iframe 或链接自身的名称。

<header> 的默认无障碍角色取决于上下文。示例中，它位于 <section> 内，默认角色为 generic，这个角色禁止使用 aria-label 和 aria-labelledby 命名。这里的 <footer> 也有同样的问题。页面级 <header> 在符合条件时具有 banner 角色，命名规则有所不同。ARIA in HTML

因此，“aria-labelledby 在所有 header 上都已弃用”并不准确。示例中的问题是元素的默认角色禁止命名，换成 aria-label 也无法解决。

<header> 本身也不是标题。要让用户按标题导航，应使用 <h1> 至 <h6>，并根据页面层级选择级别。

图片卡片的推荐写法

如果图片只是卡片封面，没有提供标题和简介之外的信息，可以使用空替代文本：

<section
  class="docs_card"
  id="foo_a_arrays_nb"
  aria-labelledby="foo_a_arrays_nb_title"
>
  <header>
    <img
      src="/images/exemplars/foo/arrays.png"
      alt=""
    />
  </header>

  <div class="docs_card_body">
    <h3 id="foo_a_arrays_nb_title">Python arrays</h3>
    <p>Introducing python arrays.</p>
  </div>

  <footer class="card-footer">
    <p>
      <a href="https://example.com/some/path/arrays.ipynb">
        查看 Python arrays 笔记本
      </a>
    </p>
  </footer>
</section>

这里的 h3 只是示例，实际级别应根据页面结构确定。也可以把标题移进 <header>，让它和封面共同构成卡片的介绍部分。

是否使用 alt=""，取决于图片在当前页面中的用途。装饰性图片，或信息已由相邻文字完整表达的图片，可以使用空 alt，但不要直接省略该属性。WAI：装饰性图片

如果图片提供了额外信息，替代文本就应描述这些信息。下面的写法只适用于图片确实展示了相应内容的情况：

<img
  src="/images/exemplars/foo/arrays.png"
  alt="数组索引从 0 开始，示例中第一个元素通过 a[0] 访问"
/>

原来的 alt="taken from the arrays notebook" 只说明图片来源，通常没有传达图片要表达的内容。信息性图片的替代文本应保留理解当前内容所需的信息。WAI：信息性图片

链接名称应设置在 <a> 上。给 <footer> 命名，不会把“Python arrays 笔记本”自动变成内部链接的名称。直接使用具体的可见链接文字，也方便用户在链接列表中区分不同卡片。

YouTube iframe 应直接设置 title

如果卡片上方嵌入了视频，可以保留不带命名属性的 <header>，并为 iframe 设置具体的 title：

<header>
  <iframe
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Python arrays：数组入门视频"
    allowfullscreen
  ></iframe>
</header>

将 VIDEO_ID 替换为实际视频 ID，并让 title 与视频内容一致。只写“YouTube”或“视频播放器”，通常无法帮助用户区分多个视频。

title 为 iframe 提供名称，帮助用户决定是否进入该框架。它不会为框架内部的按钮命名，也不会补齐视频字幕或其他媒体替代内容。WCAG 技术 H64

如果 <header> 中包含多个相关内容，用户需要知道它们属于同一组，可以显式使用允许命名的 group 角色：

<header role="group" aria-label="Python arrays 教学资源">
  <!-- 相关图片、视频或其他内容 -->
</header>

<header> 允许使用 role="group"。单张图片或单个 iframe 通常通过自身的替代文本或名称就能说明用途，无须再增加一层分组名称。ARIA in HTML

如果需要可见的图注，可以考虑 <figure> 和 <figcaption>。图注提供上下文，图片仍应根据用途设置合适的 alt。

还需要注意什么？

aria-labelledby 支持引用多个 ID，按顺序组合名称，原代码中的这种用法是允许的。直接引用的隐藏文本也可能参与名称计算，因此不能仅凭 aria-hidden="true" 判断这些文字一定不会被读出。另外，aria-hidden 不会在视觉上隐藏段落。无障碍名称计算规范

这类卡片通常不需要专门拼接“Contains graphic for…”或“Contains link to…”。简洁的内容名称更容易理解，屏幕阅读器还会根据元素语义提供角色信息。APG：名称与描述

保留 <section aria-labelledby="…"> 会使其成为有名称的 region 地标。如果页面有大量卡片，应评估是否需要让每张卡片都成为地标，以免增加导航负担。ARIA in HTML

检查无障碍树中的角色和名称后，还应实际测试标题导航、链接导航及视频键盘操作。通过自动化检查，只能说明工具覆盖的规则没有发现问题，不能保证最终使用体验。

如何为 HTML 卡片中包含图片或视频的 header 设置无障碍名称？

结论

为什么这里不能给 header 添加名称？

图片卡片的推荐写法

YouTube iframe 应直接设置 title

确实需要为整个 header 分组命名时

还需要注意什么？