accessibility

UI5 Web Components 中的无障碍功能

UI5 Web Components 内置了无障碍功能：ARIA 角色、键盘导航、屏幕阅读器支持和高对比度主题都会在 shadow DOM 中自动处理。应用应使用此处介绍的无障碍 API，提供只有应用才了解的额外上下文（标签、描述、关系）。

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

组件会自动提供：

• ARIA 角色和属性，在 shadow DOM 中映射（例如，ui5-combobox 会在内部渲染 role="combobox"）
• 键盘导航，支持在复杂组件中导航（列表、表格、日期选择器等中的方向键）
• 焦点管理，提供可见的焦点指示器
• 状态映射——disabled、readonly、required、checked 会自动映射为对应的 ARIA 属性（aria-disabled、aria-readonly、aria-required、aria-checked）

无障碍 API

使用这些属性，为应用补充无障碍上下文。

accessibleName

映射到 aria-label。当可见标签不够充分或不存在时，提供文本替代内容。

<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

aria-labelledby 的替代方案，可跨越 shadow DOM 边界。接受一个或多个元素的 ID，这些元素的文本内容将用作标签。

<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，这样标签与 ARIA 文本会自动保持同步。

accessibleDescription / accessibleDescriptionRef

映射到 aria-description。提供标签之外的补充描述文本。

<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

覆盖组件的默认 ARIA 角色。

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

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

accessibilityAttributes

用于在组件的根元素上设置额外 ARIA 属性的对象。可用于 aria-expanded、aria-haspopup、aria-controls 等关系属性。

<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 文档。

标签与输入框的关系

由于 shadow DOM 的存在，标准 HTML <label for="..."> 对自定义元素不起作用。请改用以下模式：

使用 Label 的 for 属性（表单中首选）：

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

for 属性会将标签与输入框关联起来。点击标签会将焦点置于输入框上。在标签上设置 required 会显示星号；在输入框上设置 required 会设置 aria-required。

使用 accessibleNameRef：

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

标题与语义级别

使用 ui5-title 的 level 属性和 ui5-panel 的 header-level 属性，为文档大纲设置正确的标题级别。

<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）属于无障碍违规。

图标无障碍功能

ui5-icon 组件的 mode 属性用于控制其无障碍行为：

模式	行为	适用情况
Image（默认）	role="img"	图标表达含义（需要设置 accessible-name）
Interactive	role="button"，可聚焦	图标可点击
Decorative	aria-hidden="true"	图标纯属视觉装饰，不表达含义

<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。

隐式消息播报

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

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);

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

工具提示

请使用 tooltip 属性，而不是原生的 title 属性。

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

不要直接在自定义元素上设置 title，这可能导致重复的语音播报或辅助功能树映射错误。

高对比度和主题

UI5 Web Components 提供高对比度主题：

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

检测操作系统偏好设置并应用相应主题：

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();

快速参考

目标	属性 / 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()