aria-label的核心作用是为没有可见文本的元素提供屏幕阅读器可读的替代名称；它不改变视觉呈现，仅影响辅助技术如何朗读该元素，但滥用会覆盖原生语义，导致可访问性倒退。

aria-label 的核心作用是：**为没有可见文本的元素提供屏幕阅读器可读的替代名称**。它不改变视觉呈现，只影响辅助技术如何“说出”这个元素——但滥用会直接覆盖原生语义，导致可访问性倒退。

什么时候必须用 aria-label？

仅限以下真实场景：

• 纯图标按钮，比如 ，内部无文字，又不能改造成带文本的按钮
• 搜索框、筛选控件等上下文极明确的输入框，且无法加 （例如被封装在第三方组件里）
• 面包屑导航根容器：
  ，用于区分多个
  区域
• 模态框标题未包裹在
  等语义标签内时，临时补位：
  ...

  确认删除

  —— 这里不该用 aria-label，而该用 aria-labelledby

  常见误用：给

  用户设置

  加 aria-label="设置页面"，这会让屏幕阅读器跳过“用户设置”，只读“设置页面”，造成信息丢失和冗余。

  aria-label 和 aria-labelledby 怎么选？

  判断依据就一个：**元素附近有没有现成的、可见的、语义匹配的文本？**

  • 有，就用 aria-labelledby="id"，让屏幕阅读器去读那个元素的内容——比如图标旁有个 保存，按钮写
  • 没有，才用 aria-label="保存" 直接写死字符串
  • aria-labelledby 支持多 ID 引用：aria-labelledby="icon-desc title-text"，读屏器会按顺序拼接朗读
  • aria-label 优先级高于内部文本：写成 发送，“发送”会被完全忽略

  哪些地方绝对不能加 aria-label？

  这些位置加了不仅没用，还会破坏可访问性：

  

  Convert Markdown To HTML And PDF - Markdown和HTML、PDF互转

  实现 Markdown↔ HTML 互转，支持导出 PDF，用于用户请求的文档格式转换。

  下载

  • 到
    标题元素：它们的可访问名称就是自身文本，aria-label 会覆盖它，触发 nu html checker 警告 “possible misuse of aria-label”
  • 元素：应该用 alt 属性，aria-label 在这里无效或行为不可靠
  • 等原生表单控件：已有隐式语义，加 aria-label 可能与 冲突；没 时，优先补 ，次选 aria-label
  • 已含可见文本的按钮：导出 PDF 不需要也不该加 aria-label

  特别注意：自定义开关（非 ）若用了 role="switch"，必须配 aria-checked 和键盘支持，但依然不该用 aria-label 描述状态——状态变化应由 aria-checked 驱动，读屏器自动播报“已启用”/“已禁用”。

  调试和验证的关键点

  别信 DevTools 里属性存在就万事大吉：

  • 用 NVDA + Chrome 或 VoiceOver + Safari 实际走一遍 Tab 流程，听它怎么读那个按钮
  • 检查焦点是否能自然落到该元素上（tabindex="-1" 会导致键盘用户进不去）
  • 如果元素是动态插入的（比如 JS 渲染的图标按钮），确保 aria-label 在 DOM 挂载完成时已存在，而不是靠后续 JS 补充
  • aria-label 值必须是静态字符串，不能是变量拼接后空值或空格——aria-label=" " 会被当成无名元素，读屏器可能跳过

  最常被漏掉的是：视觉隐藏的分隔符（如面包屑里的 /）必须同步加 aria-hidden="true"，否则会被读成“斜杠”；而当前页的

• 必须加 aria-current="page"，不是 aria-disabled="true"——这是两个完全不同的语义。