maui-accessibility

.NET MAUI のアクセシビリティ

プラットフォーム固有の重要な注意点

1. Label に Description を設定しない

SemanticProperties.Description を Label に設定すると、スクリーンリーダーでは Text プロパティが上書きされます。ラベルが二度読み上げられたり、予期しない動作をしたりする可能性があります。

<Label Text="Welcome"
       SemanticProperties.Description="Welcome" />


<Label Text="Welcome" />

2. Android の Entry／Editor：Description を設定すると TalkBack の操作ヒントが失われる

Android では、Entry または Editor に SemanticProperties.Description を設定すると、 TalkBack で「ダブルタップして編集」の操作ヒントが表示されなくなります。

<Entry SemanticProperties.Description="Email address" />


<Entry Placeholder="Email address" />

3. iOS：親要素に Description を設定すると子要素が隠れる

iOS／VoiceOver では、レイアウトに SemanticProperties.Description を設定すると、 コンテナー全体が 1 つのアクセシブル要素になります。子要素にはアクセスできなくなります。

<HorizontalStackLayout SemanticProperties.Description="User info">
    <Label Text="Name:" />
    <Label Text="Alice" />
</HorizontalStackLayout>


<HorizontalStackLayout>
    <Label Text="Name:" />
    <Label Text="Alice" />
</HorizontalStackLayout>

4. Android では Hint と Entry.Placeholder が競合する

Android では、SemanticProperties.Hint と Entry.Placeholder は同じ Android 属性（contentDescription／hint）に対応します。両方を設定すると、一方が他方を上書きします。どちらか一方を選んでください。

5. HeadingLevel のプラットフォームによる違い

• Windows（Narrator）： 9 段階すべての見出しレベル（Level1～Level9）に対応しています。
• Android（TalkBack）／iOS（VoiceOver）： 「見出し」と「見出しではないもの」の区別にのみ対応しています。すべてのレベルが同じように扱われます。

意味的に正しくなるよう見出しレベルを使ってください。ただし、階層が反映されるのは Windows のみです。

アクセシビリティのチェックリスト

ページの監査またはアクセシビリティ対応を行う際は、次の点を確認してください。

1. 画像： 意味のある画像には SemanticProperties.Description を追加します。 装飾目的の画像には AutomationProperties.IsInAccessibleTree="false" を設定します。
2. ボタン／コントロール： アイコンのみのボタンには Description が設定されていることを確認します。 テキスト付きのボタンには通常、設定する必要はありません。
3. Entry／Editor： コンテキストを示すには Placeholder を使います。追加の説明が必要な場合のみ Hint を追加します。Description は避けてください（Android で問題が発生します）。
4. Label： Description は追加しないでください。Text をそのまま読み上げさせます。 セクション見出しには HeadingLevel を追加します。
5. 見出し： ページタイトルには Level1、セクションタイトルには Level2 などを設定します。
6. グループ化： レイアウトコンテナーへの Description の設定は避けてください（iOS で問題が発生します）。 装飾用のグループを非表示にするには ExcludedWithChildren を使います。
7. 動的コンテンツ： ステータスの変化を通知するには SemanticScreenReader.Announce を呼び出します。 ナビゲーション後またはエラー表示後には SetSemanticFocus を使います。
8. タブ順序： 論理的な順序になるよう、操作可能なコントロールに TabIndex を設定します。
9. テスト： TalkBack（Android）、VoiceOver（iOS／Mac）、Narrator （Windows）を実行し、読み上げ順序と操作を確認します。