生成具有语义属性的可访问应用

可访问性的语义与构建体验相关,使你的应用可供在各种环境中使用技术的人员使用,并为 UI 提供各种需求和体验。 在许多情况下,可访问性的法律要求可能会为开发人员提供解决辅助功能问题的推动力。 无论如何,都建议构建包含和可访问的应用程序,以便你的应用程序可以访问可能最大的受众。

重要

.NET 多平台应用 UI ( .NET MAUI) 当前为预览版。 此内容与发布之前可能会进行重大修改的预发行产品相关。 对于此处提供的信息,Microsoft 不作任何明示或暗示的担保。

(WCAG) 的 Web 内容辅助功能指南是适用于 web 和移动的全球可访问性标准和法律基准。 这些准则介绍了各种方法,这些方法可让应用程序更可识别、可执行、可理解和强大。

许多用户辅助功能需求由用户安装的辅助技术产品或由操作系统提供的工具和设置来完成。 这包括诸如屏幕阅读器、屏幕放大以及高对比度设置等功能。

屏幕阅读器通常提供显示在屏幕上的控件的听觉说明。 这些说明可帮助用户在应用中导航,并提供对没有输入或文本的控件(如图像)的引用。 屏幕阅读器通常通过触摸屏、触控板或键盘上的手势来控制。 有关启用屏幕阅读器的信息,请参阅 启用屏幕阅读器

操作系统具有自己独特的行为和配置的屏幕阅读器。 例如,大多数屏幕阅读器在收到焦点时读取与控件相关联的文本,使用户能够在应用程序中导航时自行定位。 但是,某些屏幕读取器还可以在页面出现时读取整个应用用户界面,使用户能够在尝试导航页面之前接收所有页面可用的信息性内容。

大多数屏幕阅读器会自动阅读与获得辅助功能焦点的控件关联的任何文本。 这意味着,具有 Text 属性集的控件(如 LabelButton )将可供用户访问。 但是,由于没有与之关联的文本,因此 ImageImageButtonActivityIndicator 和其他元素可能不在辅助功能树中。

.NET 多平台应用 UI ( .NET MAUI) 支持两种方法,可提供对基础平台辅助功能体验的访问。 语义属性 是在应用中提供可访问性值的 .net MAUI 方法,也是推荐的方法。 自动化属性 是在应用中提供可访问性值的 Xamarin 形式方法,已被语义属性取代。 在这两种情况下,控件的默认可访问性顺序与它们在 XAML 中列出的顺序相同,或已添加到布局中。 但是,不同的布局可能会影响可访问性顺序的其他因素。 例如,的可访问性顺序 StackLayout 也基于其方向,而的可访问性顺序基于其行和列的 Grid 排列方式。 有关内容排序的详细信息,请参阅 Xamarin 博客上 有意义的内容排序

注意

WebView当显示可访问的网站时,它也可以在 .NET MAUI 应用中访问。 相反,当显示无法访问的网站时 WebView ,它无法在 .NET MAUI 应用中访问。

语义属性

语义属性用于定义哪些控件应获得可访问性焦点,以及应大声朗读给用户的文本。 语义属性是附加属性,可将其添加到任何元素,以设置基础平台辅助功能 Api。

重要

语义属性不会尝试在每个平台上强制执行等效的行为。 相反,它们依赖于每个平台提供的辅助功能体验。

SemanticProperties类定义以下附加属性:

  • Description,类型 string 为,它表示将由屏幕读取器大声读出的说明。 有关详细信息,请参阅 Description
  • Hint类型 string 为的,它类似于 Description ,但提供其他上下文(例如控件的用途)。 有关详细信息,请参阅 提示
  • HeadingLevel,类型 SemanticHeadingLevel 为,可将元素标记为标题,以组织 UI 并使其更易于导航。 有关详细信息,请参阅 标题级别

这些附加属性设置平台可访问性值,以便屏幕阅读器可以了解元素。

说明

SemanticProperties.Description附加属性表示简短的描述性 string ,屏幕阅读器使用它来公告元素。 应为具有重要意义的元素设置此属性,这对了解内容或与用户界面交互很重要。 设置此属性可在 XAML 中完成:

<Image Source="dotnet_bot.png"
       SemanticProperties.Description="Cute dot net bot waving hi to you!" />

也可以在 c # 中设置它:

Image image = new Image { Source = "dotnet_bot.png" };
SemanticProperties.SetDescription(image, "Cute dot net bot waving hi to you!");

此外, SetValue 还可以使用方法设置 SemanticProperties.Description 附加属性:

image.SetValue(SemanticProperties.DescriptionProperty, "Cute dot net bot waving hi to you!");

警告

避免在上 Label 设置 SemanticProperties.Description 附加属性。 这将停止屏幕阅读器所说的 Text 属性。 这是因为,理想情况下,视觉对象文本应与屏幕读取器高声朗读的文本匹配。

还可以在另一个元素上定义元素的辅助功能信息。 例如,Entry 旁的 Label 可用于描述 Entry 所表示的内容。 这可以通过以下操作在 XAML 中实现:

<Label x:Name="label"
       Text="Enter your name: " />
<Entry SemanticProperties.Description="{Binding Source={x:Reference label} Path=Text}" />

或者,可在 C# 中设置如下:

Label label = new Label
{
    Text = "Enter your name: "
};
Entry entry = new Entry();
SemanticProperties.SetDescription(entry, label.Text);

提示

附加的 SemanticProperties.Hint 属性表示 string ,它为附加属性提供附加的上下文 SemanticProperties.Description ,例如控件的用途。 设置此属性可在 XAML 中完成:

<Image Source="like.png"
       SemanticProperties.Description="Like"
       SemanticProperties.Hint="Like this post." />

也可以在 c # 中设置它:

Image image = new Image { Source = "like.png" };
SemanticProperties.SetDescription(image, "Like");
SemanticProperties.SetHint(image, "Like this post.");

此外, SetValue 还可以使用方法设置 SemanticProperties.Hint 附加属性:

image.SetValue(SemanticProperties.HintProperty, "Like this post.");

在 Android 上,此属性的行为方式略有不同,具体取决于它附加到的控件。 例如,对于没有文本值的控件(如 SwitchCheckBox ),控件将显示该控件的提示。 但对于带有文本值的控件,不显示提示,并且在文本值之后读取。

警告

SemanticProperties.Hint属性与 Android 上的 Entry.Placeholder 属性冲突,这两个属性都映射到相同的平台属性。 因此,不建议将其他 SemanticProperties.Hint 值设置为 Entry.Placeholder 值。

标题级别

SemanticProperties.HeadingLevel附加属性允许将元素标记为标题,以组织 UI 并使其更易于导航。 某些屏幕阅读器使用户能够快速在标题之间跳转。

标题的级别介于1到9之间,由枚举表示 SemanticHeadingLevel ,后者定义 NoneLevel1 通过 Level9 成员。

重要

虽然 Windows 提供9个级别的标题,但 Android 和 iOS 仅提供一个标题。 因此,当设置为时 SemanticProperties.HeadingLevel Windows 它将映射到正确的标题级别。 但是,当在 Android 和 iOS 上设置时,它会映射到一个标题级别。

下面的示例演示如何设置此附加属性:

<Label Text="Get started with .NET MAUI"
       SemanticProperties.HeadingLevel="Level1" />
<Label Text="Paragraphs of text go here." />
<Label Text="Installation"
       SemanticProperties.HeadingLevel="Level2" />
<Label Text="Paragraphs of text go here." />    
<Label Text="Build your first app"
       SemanticProperties.HeadingLevel="Level3" />
<Label Text="Paragraphs of text go here." />     
<Label Text="Publish your app"
       SemanticProperties.HeadingLevel="Level4" />
<Label Text="Paragraphs of text go here." />   

也可以在 c # 中设置它:

Label label1 = new Label { Text = "Get started with .NET MAUI" };
Label label2 = new Label { Text = "Paragraphs of text go here." };
Label label3 = new Label { Text = "Installation" };
Label label4 = new Label { Text = "Paragraphs of text go here." };
Label label5 = new Label { Text = "Build your first app" };
Label label6 = new Label { Text = "Paragraphs of text go here." };
Label label7 = new Label { Text = "Publish your app" };
Label label8 = new Label { Text = "Paragraphs of text go here." };
SemanticProperties.SetHeadingLevel(label1, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label3, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label5, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label7, SemanticHeadingLevel.Level1);

此外, SetValue 还可以使用方法设置 SemanticProperties.HeadingLevel 附加属性:

label1.SetValue(SemanticProperties.HeadingLevelProperty, SemanticHeadingLevel.Level1);

语义焦点

控件具有一个 SetSemanticFocus 在命名空间中 Microsoft.Maui 定义的扩展方法,该方法将屏幕阅读器焦点强制转换为指定的元素。 例如,在给定的 Label 情况下,可以使用以下代码将已命名 label 的屏幕阅读器焦点强制置于元素:

label.SetSemanticFocus();

语义屏幕读取器

.NET MAUI Essentials 包含一个 SemanticScreenReader 类,通过该类可以指示屏幕阅读器公告指定的文本。 这可以通过调用 SemanticScreenReader.Announce 方法来实现,传递一个 string 表示文本的参数:

SemanticScreenReader.Announce("This is the announcement text.");

自动化属性

自动化属性是附加属性,可将其添加到任何元素,以指示如何向基础平台的辅助功能框架报告元素。

AutomationProperties类定义以下附加属性:

  • ExcludedWithChildren类型 bool? 的,确定是否应从辅助功能树中排除某个元素及其子元素。 有关详细信息,请参阅 ExcludedWithChildren
  • IsInAccessibleTree类型 bool? 为的,指示元素在辅助功能树中是否可用。 有关详细信息,请参阅 IsInAccessibleTree
  • Name类型 string 为的,表示作为该元素的 speakable 标识符的元素的简短说明。 有关详细信息,请参阅 Name
  • HelpText类型 string 为的,表示元素的较长说明,可将其视为与元素关联的工具提示文本。 有关详细信息,请参阅 HelpText
  • LabeledBy类型 VisualElement 为的,它使另一个元素能够为当前元素定义辅助功能信息。 有关详细信息,请参阅 LabeledBy

这些附加属性设置平台可访问性值,以便屏幕阅读器可以了解元素。

不同的屏幕阅读器读取不同的可访问性值。 因此,在使用自动化属性时,建议在每个平台上执行完全的辅助功能测试,以确保获得最佳体验。

重要

自动化属性是在应用中提供可访问性值的 Xamarin 形式方法,已被语义属性取代。 有关语义属性的详细信息,请参阅 语义属性

ExcludedWithChildren

AutomationProperties.ExcludeWithChildren类型 bool? 为的附加属性确定是否应从辅助功能树中排除某个元素及其子元素。 这可以实现类似 AbsoluteLayout 于其他布局 StackLayout (如)的情况,例如,在不可见的 StackLayout 情况下从辅助功能树中排除。 它可从 XAML 使用,如下所示:

<StackLayout AutomationProperties.ExcludedWithChildren="true">
...
</StackLayout>

或者,可在 C# 中设置如下:

StackLayout stackLayout = new StackLayout();
...
AutomationProperties.SetExcludedWithChildren(stackLayout, true);

设置此附加属性后,.NET MAUI 会将附加属性设置 AutomationProperties.IsInAccessibleTreefalse 指定元素及其子元素的。

IsInAccessibleTree

警告

此附加属性通常应保持不变。 大多数控件应出现在辅助功能树中,并且 AutomationProperties.ExcludedWithChildren 在元素及其子元素需要从辅助功能树中删除的情况下,可以设置附加属性。

AutomationProperties.IsInAccessibleTree类型 bool? 为的附加属性确定元素对屏幕读取器是否可见。 必须将其设置为 true 才能使用其他自动属性。 这可以通过以下操作在 XAML 中实现:

<Entry AutomationProperties.IsInAccessibleTree="true" />

或者,可在 C# 中设置如下:

Entry entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);

名称

重要

AutomationProperties.Name附加属性已被附加属性取代 SemanticProperties.Description

AutomationProperties.Name 附加属性值应为屏幕阅读器用于公告元素的简短的描述性文本字符串。 应为具有对理解内容或与用户界面交互重要意义的元素设置此属性。 这可以通过以下操作在 XAML 中实现:

<ActivityIndicator AutomationProperties.IsInAccessibleTree="true"
                   AutomationProperties.Name="Progress indicator" />

或者,可在 C# 中设置如下:

ActivityIndicator activityIndicator = new ActivityIndicator();
AutomationProperties.SetIsInAccessibleTree(activityIndicator, true);
AutomationProperties.SetName(activityIndicator, "Progress indicator");

HelpText

重要

AutomationProperties.HelpText附加属性已被附加属性取代 SemanticProperties.Hint

AutomationProperties.HelpText 附加属性应设置为描述用户界面元素的文本,且可视为与元素关联的工具提示文本。 这可以通过以下操作在 XAML 中实现:

<Button Text="Toggle ActivityIndicator"
        AutomationProperties.IsInAccessibleTree="true"
        AutomationProperties.HelpText="Tap to toggle the activity indicator" />

或者,可在 C# 中设置如下:

Button button = new Button { Text = "Toggle ActivityIndicator" };
AutomationProperties.SetIsInAccessibleTree(button, true);
AutomationProperties.SetHelpText(button, "Tap to toggle the activity indicator");

在某些平台上,为了编辑控件例如 Entry,有时可以省略 HelpText 属性并将其替换为占位符文本。 例如,“在此输入名字”是 Entry.Placeholder 属性的一个很好的候选对象,它在用户实际输入之前将文本放在控件中。

LabeledBy

重要

AutomationProperties.LabeledBy绑定已取代了附加属性。 有关详细信息,请参阅 SemanticProperties: Description

AutomationProperties.LabeledBy 附加属性允许另一个元素定义当前元素的可访问性信息。 例如,Entry 旁的 Label 可用于描述 Entry 所表示的内容。 这可以通过以下操作在 XAML 中实现:

<Label x:Name="label" Text="Enter your name: " />
<Entry AutomationProperties.IsInAccessibleTree="true"
       AutomationProperties.LabeledBy="{x:Reference label}" />

或者,可在 C# 中设置如下:

Label label = new Label { Text = "Enter your name: " };
Entry entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);
AutomationProperties.SetLabeledBy(entry, label);

重要

AutomationProperties.LabeledByPropertyIOS 不支持。

测试辅助功能

.NET MAUI 应用程序通常面向多个平台,这意味着根据平台测试辅助功能。 请按照以下链接,了解如何在每个平台上测试辅助功能:

以下工具可帮助你进行辅助性测试:

不过,这些工具都不能完美地模拟屏幕阅读器的用户体验,并且在具有屏幕阅读器的物理设备上,将始终手动对应用程序进行测试和故障排除的最佳方式。

启用屏幕阅读器

每个平台都有不同的默认屏幕阅读器来叙述辅助功能值:

  • Android 具有 TalkBack。 有关启用 TalkBack 的信息,请参阅 Enable TalkBack
  • iOS 和 macOS 具有 VoiceOver。 有关启用 VoiceOver 的信息,请参阅 Enable VoiceOver
  • Windows 具有讲述人。 有关启用讲述人的信息,请参阅 启用讲述人

启用 TalkBack

TalkBack 是 Android 上使用的主要屏幕阅读器。 启用的方式取决于设备制造商、Android 版本和 TalkBack 版本。 但是,通常可以通过设备设置在 Android 设备上启用 TalkBack:

  1. 打开“设置”应用 。
  2. 选择 "辅助功能TalkBack"。
  3. 启用 " 使用 TalkBack "。
  4. 选择“确定”。

注意

虽然这些步骤适用于大多数设备,但你可能会遇到一些差异。

第一次启用 TalkBack 时,TalkBack 教程会自动打开。

有关启用 TalkBack 的替代方法,请参阅 打开或关闭 TalkBack

启用 VoiceOver

VoiceOver 是在 iOS 和 macOS 上使用的主屏幕读取器。 在 iOS 上,可以启用 VoiceOver,如下所示:

  1. 打开“设置”应用 。
  2. 选择 "辅助功能TalkBack"。
  3. 启用 VoiceOver
  4. 选择“确定”。

启用 VoiceOver 后,可以通过选择 " VoiceOver 实践" 打开 VoiceOver 教程。

有关启用 VoiceOver 的替代方法,请参阅开启和实践上的 VoiceOver iPhone ,并在iPad 上打开和实践 VoiceOver

在 macOS 上,可以按如下所示启用 VoiceOver:

  1. 打开 " 系统首选项"。
  2. 选择 "辅助功能VoiceOver"。
  3. 选择 " 启用 VoiceOver"。
  4. 选择 " 使用 VoiceOver"。

可以通过选择 " 打开 VoiceOver 训练 ..." 打开 VoiceOver 教程。

有关启用 VoiceOver 的替代方法,请参阅 打开或关闭 Mac 上的 VoiceOver

启用讲述人

讲述人是 Windows 上使用的主屏幕阅读器。 讲述人可以通过一起按 WindowsCtrlEnter启用。 可以再次按下这些键来停止讲述人。

有关讲述人详细信息,请参阅 讲述人的完整指南

辅助功能清单

请遵循以下提示,确保.NET MAUI最广泛受众可以访问你的应用:

  • 遵循 Web 内容 (辅助功能指南和 WCAG 指南,确保应用可感知、可操作、可理解且) 。 WCAG 是 Web 和移动的全球可访问性标准和法律基准。 有关详细信息,请参阅 Web 内容辅助功能指南 (WCAG) 概述
  • 确保用户界面是自描述的。 测试用户界面的所有元素是否都可访问屏幕阅读器。 必要时添加描述性文本和提示。
  • 确保图像和图标具有备用文本说明。
  • 支持大字体和高对比度。 避免对控件尺寸进行硬码处理,而是首选调整大小以适应较大字体大小的布局。 在高对比度模式下测试配色方案,以确保它们可读。
  • 设计具有导航的可视化树。 使用适当的布局控件,以便使用备用输入方法在控件之间导航遵循与使用触控相同的逻辑流。 此外,从屏幕阅读器中排除不必要的元素 (例如,装饰性图像或已可访问的字段的标签) 。
  • 不要仅依赖于音频或颜色提示。 避免出现进度、完成或其他某种状态的唯一指示是声音或颜色更改的情况。 可以将用户界面设计为包含清晰的视觉提示,并仅提供用于强化的声音和颜色,或者添加特定的辅助功能指示器。 选择颜色时,请尝试避免使用难以区分颜色不全的用户的调色板。
  • 提供视频内容的标题和音频内容的可读脚本。 提供调整音频或视频内容速度的控件,并确保音量和传输控件易于查找和使用,这一点也很有帮助。
  • 当应用支持多种语言时,本地化辅助功能说明。
  • 在应用面向的每个平台上测试应用的辅助功能。 有关详细信息,请参阅 测试辅助功能