大网数据广告活动
Web 标准与前端开发

ARIA: aria-roledescription attribute

· 52CE 我爱测

The `aria-roledescription` attribute defines a human-readable, author-localized description for the role of an element.

The aria-roledescription attribute defines a human-readable, author-localized description for the role of an element.

Description

Some assistive technologies (<abbr>AT</abbr>), such as screen readers, present the role of an element as part of the user experience. The aria-roledescription attribute provides a way to define a different human-readable name to be presented by AT as the role of an element.

[!NOTE] Only use aria-roledescription to clarify the purpose of non-interactive container roles and to provide a more specific description to a widget.

Users depend on the presentation of known role name to understand the purpose of the element and, if it is a widget, how to interact with it. So, only use aria-roledescription to clarify the purpose of non-interactive container roles like group or region and to provide a more specific description to a widget.

The aria-roledescription property overrides how ATs localize and express the name of a role. When you override a role name the user understands, you can potentially negatively impact a users' ability to understand and interact with an element.

Avoid using the aria-roledescription attribute. When a use case appears special worthy of a unique roledescription, the interactions can often times be broken down into smaller pieces that have relevant roles.

When there are no semantic or ARIA widget roles that correspond to the interaction model of your widget, use role="application", provide an aria-roledescription with a human-readable, author-localized customized role name, and use aria-describedby to provide user instructions.

ATs may customize and localize the names of ARIA roles. If you are using aria-roledescription to change how the role name is presented to the user, remember to handle localization. The value should be translated when a page is localized.

Changing how the role is presented to the user has no impact on the functionality of the element. For example, if an element has a role of region or button when AT provides functions for navigating to the next region or button, if you set the aria-roledescription to continent and escape respectively, the AT will still allow those functions to navigate to regions and buttons.

Again, avoid using aria-roledescription. In this example, escape has no relevant meaning to the user, but button with "escape" as a label does.

When using aria-roledescription, also ensure that the element to which it is applied has a valid ARIA role or has implicit role semantics and that the value itself is not empty and contains more than just whitespace characters.

The aria-roledescription is required when using aria-brailleroledescription. Note that, in general, aria-brailleroledescription should only be used in rare cases when an aria-roledescription is excessively verbose when rendered in Braille.

Examples

The following example shows the use of aria-roledescription to indicate that a non-interactive container is a "slide" in a web-based presentation application.

<div
  role="article"
  aria-roledescription="slide"
  id="slide"
  aria-labelledby="slideheading">
  <h1 id="slideheading">Quarterly Report</h1>
  
</div>

In the previous examples, a screen reader user may hear "Quarterly Report, slide" rather than the less precise "Quarterly Report, article".

Values

  • <string>
    • : A non-empty string, an unconstrained value type, containing more than just white space.

Associated interfaces

  • Element.ariaRoleDescription
    • : The ariaRoleDescription property, part of the Element interface, reflects the value of the aria-roledescription attribute.
  • ElementInternals.ariaRoleDescription
    • : The ariaRoleDescription property, part of the ElementInternals interface, reflects the value of the aria-roledescription attribute.

Associated roles

Supported by all roles and by all base markup elements except for role="generic".

Specifications

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。