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

ARIA: figure role

· 52CE 我爱测

The ARIA `figure` role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular fl

The ARIA figure role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular flow of text.

Description

A figure is a perceivable section of content that typically contains a graphical document, images, code snippets, or example text. The parts of a figure MAY be user-navigable. Any content that should be grouped together and consumed as a figure (which could include images, video, audio, code snippets, or other content) can be identified as a figure using role="figure".

<div role="figure" aria-labelledby="caption">
  <img src="image.png" alt="put image description here" />
  <p id="caption">Figure 1: The caption</p>
</div>

In the above example, we have a figure that consists of two separate content items — an image and a caption. This is wrapped by a div element that identifies the content as a figure using role="figure".

For HTML, use the figure and figcaption elements. The figcaption will serve as the accessible name for the figure. When not using HTML, or when retrofitting legacy HTML, use the aria-labelledby on the figure, pointing to the figure's caption. If there is no visible caption, aria-label can be used.

<div role="figure" aria-labelledby="figure-1">
  …
  <p id="figure-1">Text that describes the figure.</p>
</div>
  • Use aria-labelledby when the text is a concise label.
  • Use aria-describedby when the text is a longer description.
  • Use aria-label when there is no visible figure caption.

This can be done semantically, without ARIA, with HTML's figure element along with figcaption.

<figure>
  <img src="image.png" alt="put image description here" />
  <figcaption>Figure 1: The caption</figcaption>
</figure>

[!NOTE] If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a figure and its caption — figure and figcaption.

Associated WAI-ARIA roles, states, and properties

  • aria-describedby
    • : The id of an element containing reference text serving as a caption.
  • aria-labelledby
    • : The id of an element containing text serving as a label.
  • aria-label
    • : If there is no element containing text that could serve as a label, you can add the label directly as a value on the aria-label on the element with the figure role or on the <figure> element.

Keyboard interactions

No role specific keyboard interactions.

Required JavaScript features

No role specific JavaScript requirements. If you don't have control over the HTML semantics, you can improve the accessibility of HTML by adding these roles and properties with JavaScript.

Examples

We could extend the initial example on the page to also identify a paragraph that provides a descriptive label for the figure by referencing its ID in aria-labelledby:

<div role="figure" aria-labelledby="figure-1">
  <img
    src="diagram.png"
    alt="diagram showing the four layers of awesome and their relative priority order —
        music, cats, nature, and ice cream" />
  <pre>
`
        let awesome = ['music', 'cats', 'nature', 'ice cream'];
      `</pre>
  <p id="figure-1">Figure 1: The four layers of awesome.</p>
</div>

Best practices

Only use role="figure" if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript.

If at all possible, you should use the appropriate semantic HTML elements to mark up a figure and its caption — figure and figcaption. For example, our above example should be rewritten as follows:

<figure>
  <img
    src="diagram.png"
    alt="diagram showing the four layers of awesome and their relative priority order —
         music, cats, nature, and ice cream" />
  <pre>
`
    let awesome = ['music', 'cats', 'nature', 'ice cream'];
  `</pre>
  <figcaption>Figure 1: The four layers of awesome.</figcaption>
</figure>

Specifications

See also

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

资料来源与适用范围

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

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

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