aria-label

aria-label 属性定义一个字符串值，用于标记交互式元素。

描述

有时，元素的默认可访问名称缺失，或者可访问名称无法准确描述元素的内容，并且 DOM 中没有可见内容可以与对象关联以赋予其意义。此类元素的一个常见示例是包含 SVG 图标且没有任何文本的按钮。

在交互式元素没有可访问名称或可访问名称不准确且 DOM 中没有可见内容可以通过aria-labelledby 属性引用的情况下，可以使用aria-label 属性定义一个字符串，用于标记设置它的交互式元素。这为交互式元素提供了其可访问名称。

以下代码显示了如何使用aria-label 属性为<button> 元素提供可访问名称的示例。此示例中的按钮包含 SVG 图形且缺少文本内容，因此aria-label 对屏幕阅读器用户了解其功能至关重要，在本例中为“关闭”。

html
<button aria-label="Close" onclick="myDialog.close()">
  <svg
    aria-hidden="true"
    focusable="false"
    width="17"
    height="17"
    xmlns="http://www.w3.org/2000/svg">
    <path
      d="m.967 14.217 5.8-5.906-5.765-5.89L3.094.26l5.783 5.888L14.66.26l2.092 2.162-5.766 5.889 5.801 5.906-2.092 2.162-5.818-5.924-5.818 5.924-2.092-2.162Z"
      fill="#000" />
  </svg>
</button>

注意：aria-label 用于交互式元素或通过其他 ARIA 声明使其成为交互式元素的元素，前提是 DOM 中没有可见文本用作标签。

大多数内容都具有从其直接包装元素的文本内容生成的可用名称。可访问名称也可以由某些属性或关联元素创建。

默认情况下，按钮的可访问名称是<button> 标记之间包含的内容，图像的可访问名称是其alt 属性的内容，表单输入的可访问名称是关联的<label> 元素的内容。

如果这些选项均不可用，或者默认的可访问名称不合适，请使用aria-label 属性定义元素的可访问名称。

注意：虽然aria-label 可以用于任何可以具有可访问名称的元素，但在实践中，它仅支持交互式元素、小部件、地标、图像和 iframe。

使用aria-label 时，还需要考虑aria-labelledby

  • aria-label 可用于可能标记元素的文本不可见的情况。如果存在可见文本标记元素，请改用aria-labelledby。
  • aria-label 的用途与aria-labelledby 相同。两者都为元素提供可访问名称。如果元素没有可见名称可以引用，请使用aria-label 为用户提供可识别的可访问名称。如果 DOM 中提供了标签文本，并且可以将其引用以获得可接受的用户体验，则优先使用aria-labelledby。不要在同一元素上同时使用两者，因为如果同时应用两者，aria-labelledby 优先于aria-label。

使用aria-label 时，请牢记以下其他指南

  • aria-label 属性可以与常规语义 HTML 元素一起使用；它不限于分配了ARIA role 的元素。
  • 不要“过度使用”aria-label。请记住，它主要用于辅助技术。要提供其他说明或阐明 UI，请使用可见文本和aria-describedby 或aria-description，而不是aria-label。说明应供所有用户访问，而不仅仅是使用屏幕阅读器的用户（或者最好是使您的 UI 更直观）。

    注意：由于aria-label 内容不会在辅助技术之外显示，因此请考虑将重要信息显示给所有用户。

  • 并非所有元素都能获得可访问名称。对于内联结构角色（例如code、term和emphasis）以及未映射到可访问性 API 的角色（包括none），都不应使用aria-label或aria-labelledby。aria-label属性适用于包括链接、视频、表单控件以及具有地标角色或窗口部件角色的元素；当 DOM 中不存在可见标签时，aria-label提供可访问名称。
  • 如果为<iframe>分配title，为<img>定义alt属性，或为<input>添加<label>，则不需要aria-label。但是，如果存在aria-label属性，它将优先于 iframe 的title、图像的alt或输入的<label>文本，作为该元素的可访问名称。

值

<string>

将作为对象可访问名称的文本字符串。

关联接口

Element.ariaLabel

ariaLabel属性是Element接口的一部分，它反映了aria-label属性的值。

ElementInternals.ariaLabel

ariaLabel属性是ElementInternals接口的一部分，它反映了aria-label属性的值。

关联角色

几乎所有角色都使用，**除了**作者无法为其提供可访问名称的角色。

aria-label属性**不支持**以下元素：

规范

规范
可访问的富互联网应用程序 (WAI-ARIA)
# aria-label

另请参阅