accessibility

UI5 Web Components のアクセシビリティ

UI5 Web Components には、ARIA ロール、キーボード操作、スクリーンリーダーのサポート、高コントラストテーマなどのアクセシビリティ機能が組み込まれており、シャドウ DOM 内で自動的に処理されます。アプリケーションでは、アプリだけが把握している追加のコンテキスト（ラベル、説明、関連付け）を提供するために、ここで説明するアクセシビリティ API を使用してください。

組み込みのアクセシビリティ（アプリのコードは不要）

コンポーネントは次の機能を自動的に提供します。

• ARIA ロールと属性をシャドウ 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>

表示されるテキストラベルがない場合、たとえばアイコンのみのボタンや <ui5-label> のない入力欄では、accessibleName を使用してください。

accessibleNameRef

シャドウ DOM の境界を越えて機能する、aria-labelledby の代替手段です。テキストコンテンツをラベルとして使用する要素の ID を1つ以上指定します。

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

表示されるラベルがある場合は、accessibleName よりも 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 ドキュメントを確認してください。

ラベルと入力欄の関連付け

シャドウ 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 を使用します

ツールチップ

ネイティブの title 属性ではなく、tooltip プロパティを使用してください。

<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	ハイコントラストホワイト

OS の設定を検出し、適切なテーマを適用します。

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 ではありません）
OS のコントラスト設定に対応する	prefers-contrast メディアクエリと setTheme() を使用する