accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accessibility in UI5 Web Components

UI5 Web Components中的无障碍访问

UI5 Web Components have built-in accessibility: ARIA roles, keyboard navigation, screen reader support, and high contrast themes are handled automatically in the shadow DOM. Applications should use the accessibility APIs described here to provide additional context that only the app can know (labels, descriptions, relationships).

UI5 Web Components内置无障碍访问能力：ARIA角色、键盘导航、屏幕阅读器支持以及高对比度主题会在shadow DOM中自动处理。应用应使用本文所述的无障碍API来提供只有应用本身才能知晓的额外上下文信息（标签、描述、关联关系）。

Built-in Accessibility (No App Code Needed)

内置无障碍能力（无需编写应用代码）

Components automatically provide:

ARIA roles and attributes mapped in the shadow DOM (e.g.,
```
ui5-combobox
```
renders
```
role="combobox"
```
internally)
Keyboard navigation within complex components (arrow keys in lists, tables, date pickers, etc.)
Focus management with visible focus indicators

State mapping —

disabled

readonly

required

checked

are automatically mapped to their ARIA equivalents (

aria-disabled

aria-readonly

aria-required

aria-checked

)

组件会自动提供：

ARIA角色与属性：在shadow DOM中映射（例如，
```
ui5-combobox
```
内部会渲染
```
role="combobox"
```
）
键盘导航：在复杂组件内支持（列表、表格、日期选择器等中的箭头键操作）
焦点管理：带有可见的焦点指示器

状态映射：

disabled

、

readonly

、

required

、

checked

会自动映射为对应的ARIA等效属性（

aria-disabled

、

aria-readonly

、

aria-required

、

aria-checked

）

Accessibility APIs

无障碍API

Use these properties to enrich the accessibility context for your application.

使用以下属性丰富应用的无障碍上下文信息。

accessibleName

Maps to

aria-label

. Provides a text alternative when the visual label is insufficient or absent.

html

<ui5-button icon="sap-icon://edit" accessible-name="Edit document"></ui5-button>

<ui5-combobox accessible-name="Select country">
    <ui5-cb-item text="Germany"></ui5-cb-item>
</ui5-combobox>

Use

accessibleName

when there is no visible text label, for example icon-only buttons or inputs without a

<ui5-label>

映射至

aria-label

。当视觉标签不足或不存在时，提供文本替代方案。

html

<ui5-button icon="sap-icon://edit" accessible-name="Edit document"></ui5-button>

<ui5-combobox accessible-name="Select country">
    <ui5-cb-item text="Germany"></ui5-cb-item>
</ui5-combobox>

当没有可见文本标签时使用

accessibleName

，例如纯图标按钮或没有

<ui5-label>

的输入框。

accessibleNameRef

Alternative to

aria-labelledby

that works across shadow DOM boundaries. Takes one or more IDs of elements whose text content serves as the label.

html

<ui5-label id="lblName">Full name</ui5-label>
<ui5-input accessible-name-ref="lblName"></ui5-input>

<!-- Multiple refs -->
<span id="prefix">Shipping</span>
<ui5-label id="lblAddr">Address</ui5-label>
<ui5-input accessible-name-ref="prefix lblAddr"></ui5-input>

Prefer

accessibleNameRef

over

accessibleName

when a visible label exists — this keeps the label and the ARIA text in sync automatically.

是

aria-labelledby

的替代方案，可跨shadow DOM边界工作。接收一个或多个元素的ID，这些元素的文本内容将作为标签。

html

<ui5-label id="lblName">Full name</ui5-label>
<ui5-input accessible-name-ref="lblName"></ui5-input>

<!-- 多个引用 -->
<span id="prefix">Shipping</span>
<ui5-label id="lblAddr">Address</ui5-label>
<ui5-input accessible-name-ref="prefix lblAddr"></ui5-input>

当存在可见标签时，优先使用

accessibleNameRef

而非

accessibleName

——这能让标签与ARIA文本自动保持同步。

accessibleDescription / accessibleDescriptionRef

Maps to

aria-description

. Provides additional descriptive text beyond the label.

html

<ui5-input accessible-name="Password"
           accessible-description="Must be at least 8 characters">
</ui5-input>

<!-- Or reference an existing element -->
<p id="hint">Must be at least 8 characters</p>
<ui5-input accessible-name="Password"
           accessible-description-ref="hint">
</ui5-input>

映射至

aria-description

。提供超出标签范围的额外描述文本。

html

<ui5-input accessible-name="Password"
           accessible-description="Must be at least 8 characters">
</ui5-input>

<!-- 或引用现有元素 -->
<p id="hint">Must be at least 8 characters</p>
<ui5-input accessible-name="Password"
           accessible-description-ref="hint">
</ui5-input>

accessibleRole

Overrides the default ARIA role of a component.

html

<ui5-panel accessible-role="Complementary">...</ui5-panel>
<ui5-list accessible-role="Menu">...</ui5-list>
<ui5-button accessible-role="Link">Navigate</ui5-button>

Only change the role when the component is used in a non-standard way (e.g., a List used as a menu).

覆盖组件的默认ARIA角色。

html

<ui5-panel accessible-role="Complementary">...</ui5-panel>
<ui5-list accessible-role="Menu">...</ui5-list>
<ui5-button accessible-role="Link">Navigate</ui5-button>

仅当组件以非标准方式使用时才更改角色（例如，将List用作菜单）。

accessibilityAttributes

An object that sets additional ARIA attributes on the component's root element. Use for

aria-expanded

aria-haspopup

aria-controls

, and similar relationship attributes.

html

<ui5-button id="menuBtn">Open Menu</ui5-button>
<ui5-menu id="menu">...</ui5-menu>

<script>
document.getElementById("menuBtn").accessibilityAttributes = {
    expanded: false,
    hasPopup: "menu",
    controls: "menu"
};
</script>

For composite components like

ui5-shellbar

, the object contains nested objects for different internal elements — check the component's API docs.

一个对象，用于在组件的根元素上设置额外的ARIA属性。适用于

aria-expanded

、

aria-haspopup

、

aria-controls

等关联属性。

html

<ui5-button id="menuBtn">Open Menu</ui5-button>
<ui5-menu id="menu">...</ui5-menu>

<script>
document.getElementById("menuBtn").accessibilityAttributes = {
    expanded: false,
    hasPopup: "menu",
    controls: "menu"
};
</script>

对于

ui5-shellbar

等复合组件，该对象包含针对不同内部元素的嵌套对象——请查看组件的API文档。

Label-Input Relationships

标签与输入框的关联

Due to shadow DOM, standard HTML

<label for="...">

does not work with custom elements. Use these patterns instead:

Using Label's
for
property (preferred for forms):

html

<ui5-label for="nameInput" required show-colon>Name</ui5-label>
<ui5-input id="nameInput" required></ui5-input>

The

for

property connects the label to the input. Clicking the label focuses the input. Setting

required

on the label shows an asterisk; setting

required

on the input sets

aria-required

Using
accessibleNameRef
:

html

<ui5-label id="dateLabel">Date of birth</ui5-label>
<ui5-date-picker accessible-name-ref="dateLabel"></ui5-date-picker>

由于shadow DOM的存在，标准HTML的

<label for="...">

无法与自定义元素配合使用。请改用以下模式：

使用Label的
for
属性（表单优先选择）：

html

<ui5-label for="nameInput" required show-colon>Name</ui5-label>
<ui5-input id="nameInput" required></ui5-input>

for

属性将标签与输入框关联。点击标签会聚焦输入框。在标签上设置

required

会显示星号；在输入框上设置

required

会设置

aria-required

。

使用
accessibleNameRef
：

html

<ui5-label id="dateLabel">Date of birth</ui5-label>
<ui5-date-picker accessible-name-ref="dateLabel"></ui5-date-picker>

Headings and Semantic Levels

标题与语义层级

Use the

level

property on

ui5-title

and

header-level

ui5-panel

to set the correct heading level for the document outline.

html

<ui5-title level="H1">Page Title</ui5-title>

<ui5-panel header-text="Settings" header-level="H2">
    <ui5-title level="H3">General</ui5-title>
</ui5-panel>

Screen readers use heading levels to build a page outline. Skipping levels (e.g., H1 to H4) is an accessibility violation.

在

ui5-title

上使用

level

属性，在

ui5-panel

上使用

header-level

属性，为文档大纲设置正确的标题层级。

html

<ui5-title level="H1">Page Title</ui5-title>

<ui5-panel header-text="Settings" header-level="H2">
    <ui5-title level="H3">General</ui5-title>
</ui5-panel>

屏幕阅读器会使用标题层级构建页面大纲。跳过层级（例如从H1直接到H4）属于无障碍访问违规。

Icon Accessibility

图标无障碍访问

The

ui5-icon

component has a

mode

property that controls its accessible behavior:

Mode	Behavior	Use when
`Image` (default)	`role="img"`	Icon conveys meaning (needs `accessible-name` )
`Interactive`	`role="button"` , focusable	Icon is clickable
`Decorative`	`aria-hidden="true"`	Icon is purely visual, no meaning

html

<!-- Meaningful icon — needs accessible-name -->
<ui5-icon name="sap-icon://warning" mode="Image"
          accessible-name="Warning"></ui5-icon>

<!-- Clickable icon -->
<ui5-icon name="sap-icon://delete" mode="Interactive"
          accessible-name="Delete item"></ui5-icon>

<!-- Decorative icon — hidden from screen readers -->
<ui5-icon name="sap-icon://favorite" mode="Decorative"></ui5-icon>

Always set

accessible-name

on icons in

Image

Interactive

mode.

ui5-icon

组件有一个

mode

属性，用于控制其无障碍行为：

模式	行为	适用场景
`Image` （默认）	`role="img"`	图标传递含义（需要 `accessible-name` ）
`Interactive`	`role="button"` ，可聚焦	图标可点击
`Decorative`	`aria-hidden="true"`	图标仅为视觉装饰，无实际含义

html

<!-- 有含义的图标 —— 需要设置accessible-name -->
<ui5-icon name="sap-icon://warning" mode="Image"
          accessible-name="Warning"></ui5-icon>

<!-- 可点击的图标 -->
<ui5-icon name="sap-icon://delete" mode="Interactive"
          accessible-name="Delete item"></ui5-icon>

<!-- 装饰性图标 —— 对屏幕阅读器隐藏 -->
<ui5-icon name="sap-icon://favorite" mode="Decorative"></ui5-icon>

对于处于

Image

或

Interactive

模式的图标，务必设置

accessible-name

。

Invisible Messaging

隐形消息

Use

InvisibleMessage

to announce dynamic content changes to screen readers (e.g., search results count, form validation, live updates).

javascript

import announce from "@ui5/webcomponents-base/dist/util/InvisibleMessage.js";
import InvisibleMessageMode from "@ui5/webcomponents-base/dist/types/InvisibleMessageMode.js";

// Polite: announced at the next pause (e.g., search results)
announce("5 results found", InvisibleMessageMode.Polite);

// Assertive: announced immediately (e.g., errors)
announce("Invalid email address", InvisibleMessageMode.Assertive);

Use Polite for non-urgent updates (search results, status changes)
Use Assertive for urgent notifications (errors, warnings)

使用

InvisibleMessage

向屏幕阅读器播报动态内容变化（例如搜索结果数量、表单验证、实时更新）。

javascript

import announce from "@ui5/webcomponents-base/dist/util/InvisibleMessage.js";
import InvisibleMessageMode from "@ui5/webcomponents-base/dist/types/InvisibleMessageMode.js";

// Polite：在下次停顿时分播报（例如搜索结果）
announce("5 results found", InvisibleMessageMode.Polite);

// Assertive：立即播报（例如错误信息）
announce("Invalid email address", InvisibleMessageMode.Assertive);

对于非紧急更新（搜索结果、状态变化），使用Polite模式
对于紧急通知（错误、警告），使用Assertive模式

Tooltip

工具提示

Use the

tooltip

property instead of the native

title

attribute.

html

<ui5-button icon="sap-icon://edit" tooltip="Edit document"></ui5-button>

Do not set

title

directly on custom elements — this can cause repetitive speech output or incorrect accessibility tree mapping.

使用

tooltip

属性替代原生的

title

属性。

html

<ui5-button icon="sap-icon://edit" tooltip="Edit document"></ui5-button>

请勿直接在自定义元素上设置

title

——这可能导致重复语音输出或无障碍树映射错误。

High Contrast and Theming

高对比度与主题

UI5 Web Components ship with high contrast themes:

Theme	Use case
`sap_horizon`	Default light theme
`sap_horizon_dark`	Dark theme
`sap_horizon_hcb`	High Contrast Black
`sap_horizon_hcw`	High Contrast White

Detect OS preferences and apply the appropriate theme:

javascript

import { setTheme } from "@ui5/webcomponents-base/dist/config/Theme.js";

const darkMode = window.matchMedia("(prefers-color-scheme: dark)");
const highContrast = window.matchMedia("(prefers-contrast: more)");

function applyTheme() {
    if (highContrast.matches) {
        setTheme(darkMode.matches ? "sap_horizon_hcb" : "sap_horizon_hcw");
    } else {
        setTheme(darkMode.matches ? "sap_horizon_dark" : "sap_horizon");
    }
}

darkMode.onchange = applyTheme;
highContrast.onchange = applyTheme;
applyTheme();

UI5 Web Components附带高对比度主题：

主题	适用场景
`sap_horizon`	默认浅色主题
`sap_horizon_dark`	深色主题
`sap_horizon_hcb`	高对比度黑色主题
`sap_horizon_hcw`	高对比度白色主题

检测系统偏好并应用相应主题：

javascript

import { setTheme } from "@ui5/webcomponents-base/dist/config/Theme.js";

const darkMode = window.matchMedia("(prefers-color-scheme: dark)");
const highContrast = window.matchMedia("(prefers-contrast: more)");

function applyTheme() {
    if (highContrast.matches) {
        setTheme(darkMode.matches ? "sap_horizon_hcb" : "sap_horizon_hcw");
    } else {
        setTheme(darkMode.matches ? "sap_horizon_dark" : "sap_horizon");
    }
}

darkMode.onchange = applyTheme;
highContrast.onchange = applyTheme;
applyTheme();

Quick Reference

快速参考

Goal	Property / API
Label a component without visible text	`accessible-name="..."`
Link a visible label to a component	`accessible-name-ref="labelId"` or `<ui5-label for="inputId">`
Add a description	`accessible-description="..."` or `accessible-description-ref="id"`
Change ARIA role	`accessible-role="..."`
Set expanded/haspopup/controls	`accessibilityAttributes = { expanded, hasPopup, controls }`
Set heading level	`level="H2"` on Title, `header-level="H2"` on Panel
Make icon accessible	`mode="Image"` + `accessible-name="..."`
Hide decorative icon	`mode="Decorative"`
Announce dynamic changes	`announce(message, InvisibleMessageMode.Polite)`
Set tooltip	`tooltip="..."` (not `title` )
Respond to OS contrast settings	Use `prefers-contrast` media query + `setTheme()`

目标	属性/API
为无可见文本的组件设置标签	`accessible-name="..."`
将可见标签与组件关联	`accessible-name-ref="labelId"` 或 `<ui5-label for="inputId">`
添加描述	`accessible-description="..."` 或 `accessible-description-ref="id"`
修改ARIA角色	`accessible-role="..."`
设置expanded/haspopup/controls	`accessibilityAttributes = { expanded, hasPopup, controls }`
设置标题层级	在Title上使用 `level="H2"` ，在Panel上使用 `header-level="H2"`
让图标具备无障碍访问能力	`mode="Image"` + `accessible-name="..."`
隐藏装饰性图标	`mode="Decorative"`
播报动态变化	`announce(message, InvisibleMessageMode.Polite)`
设置工具提示	`tooltip="..."` （而非 `title` ）
响应系统对比度设置	使用 `prefers-contrast` 媒体查询 + `setTheme()`