maui-accessibility

.NET MAUI 无障碍功能

关键平台注意事项

1. 不要在 Label 上设置 Description

在 Label 上设置 SemanticProperties.Description 会对屏幕阅读器覆盖 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 会将 整个容器设为单个可访问元素，导致子元素无法访问。

<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. 输入框/编辑器：使用 Placeholder 提供上下文。仅在需要额外说明时添加 Hint。避免使用 Description（会导致 Android 上的问题）。
4. 标签：不要添加 Description，让 Text 自行朗读。 为分区标题添加 HeadingLevel。
5. 标题：将页面标题标记为 Level1，分区标题标记为 Level2，依此类推。
6. 分组：避免在布局容器上使用 Description（会导致 iOS 上的问题）。 使用 ExcludedWithChildren 隐藏装饰性分组。
7. 动态内容：状态变化时调用 SemanticScreenReader.Announce。导航或显示错误后使用 SetSemanticFocus。
8. Tab 顺序：为交互控件设置 TabIndex，确保顺序符合逻辑。
9. 测试：运行 TalkBack（Android）、VoiceOver（iOS/Mac）和 Narrator （Windows），验证朗读顺序和操作。