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

ARIA: heading role

· 52CE 我爱测

The `heading` role defines this element as a heading to a page or section, with the `aria-level` attribute providing for more structure.

The heading role defines this element as a heading to a page or section, with the aria-level attribute providing for more structure.

Description

The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading. In addition, the level tells assistive technologies which part of the page structure this heading represents. A level 1 heading, indicated with aria-level="1", usually indicates the main heading of a page, a level 2 heading, defined with aria-level="2" the first subsection, a level 3 is a subsection of that, and so on.

<div role="heading" aria-level="1">This is a main page heading</div>

This defines the text in the <div> to be the main heading of the page, indicated by being level 1 via the aria-level attribute. Opt for using the Heading_Elements (through Heading_Elements) element instead.

<h1>This is a main page heading</h1>

Associated WAI-ARIA roles, states, and properties

  • aria-level
    • : The aria-level attribute specifies the heading level in the document structure. This attribute is required: authors must indicate the proper nesting level to ensure elements with a role of heading are organized into a logical outline. If the attribute is erroneously unspecified, then browsers will use a fallback value of 2.

Keyboard interactions

This role does not require any special keyboard navigation. As with any heading, giving it an ID ensures it can be referenced from anchor links, making it accessible via the keyboard.

Required JavaScript features

  • Required event handlers
    • : None.
  • Changing attribute values
    • : Usually not required, unless dynamically inserting content. In that case, the newly-added headings need aria-level attributes whose values are consistent with the rest of the document structure.

[!NOTE] Instead of using a <div> or <span> with a heading role and aria-level, consider using a native Heading_Elements through Heading_Elements elements instead to indicate that this text is a heading, and what part of the structure it represents.

Examples

The following shows a typical page structure.

<div id="container">
  <div role="heading" aria-level="1">The main page heading</div>
  <p>This article is about showing a page structure.</p>
  <div role="heading" aria-level="2">Introduction</div>
  <p>An introductory text.</p>
  <div role="heading" aria-level="2">Chapter 1</div>
  <p>Text</p>
  <div role="heading" aria-level="3">Chapter 1.1</div>
  <p>More text in a sub section.</p>
</div>

However, instead, you should do:

<div id="container">
  <h1>The main page heading</h1>
  <p>This article is about showing a page structure.</p>
  <h2>Introduction</h2>
  <p>An introductory text.</p>
  <h2>Chapter 1</h2>
  <p>Text</p>
  <h3>Chapter 1.1</h3>
  <p>More text in a sub section.</p>
</div>

Accessibility concerns

[!WARNING] Using aria-label or aria-labelledby will hide the content of your heading from assistive technologies, reading the label instead of the heading.

If you must use the heading role and aria-level attribute, do not go over level 6 so that you are consistent with HTML. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser and screen reader combinations.

Best practices

The best way to use this role is to not use it at all, and instead use the native heading tags Heading_Elements through Heading_Elements as shown in the example above. The heading role and aria-level attribute should only be used to retrofit accessibility on legacy code that you cannot make major changes to.

Instead of using the ARIA heading role, use the semantic HTML element:

HTML Element heading role
Heading_Elements <div role="heading" aria-level="1">
Heading_Elements <div role="heading" aria-level="2">
Heading_Elements <div role="heading" aria-level="3">
Heading_Elements <div role="heading" aria-level="4">
Heading_Elements <div role="heading" aria-level="5">
Heading_Elements <div role="heading" aria-level="6">

Added benefits

None.

Specifications

Precedence order

The heading role overrides the native semantic meaning of the element it is being used for. The aria-level attribute, in addition, determines what level of heading is being exposed.

See also

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

资料来源与适用范围

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

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

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