公开基础无障碍信息

辅助功能原则与名称、角色和值相关。本主题演示如何在应用中公开这些属性，以便辅助技术可以正确解释 UI。

可访问名称

可访问名称是屏幕阅读器为 UI 元素报告的标签。在传达含义或支持交互的元素上设置它，包括图像、输入字段、按钮、控件和区域。

下表介绍了如何在 XAML UI 中定义或获取各种类型的元素的可访问名称。

元素类型	DESCRIPTION
静态文本	对于 TextBlock 和 RichTextBlock 元素，可访问的名称会自动从可见（内部）文本中确定。该元素中的所有文本都用作名称。请参阅内部文本名称。
映像	XAML Image 元素没有直接对应 HTML img 和类似元素的 alt 属性。使用 AutomationProperties.Name 来提供名称，或者使用字幕说明技术。请参阅图像的可访问名称。
表单元素	窗体元素的可访问名称应与为该元素显示的标签相同。请参阅标签和 LabeledBy。
按钮和链接	默认情况下，按钮或链接的可访问名称基于可见文本，使用与内文本名称中所述相同的规则。如果按钮仅包含图像，请使用 AutomationProperties.Name 来提供一个文本描述，说明按钮的预期操作。

大多数容器元素（如面板）不公开可访问的名称。在 UI 自动化中，有意义的子项应提供名称和角色，而容器主要公开遍历的结构。

角色与价值

XAML 控件通过其内置的 UI 自动化支持公开角色（如果适用，还会公开值）。使用 UI 自动化工具或在每个控件的 AutomationPeer 文档中检查这些属性。角色映射到 AutomationControlType，并通过控件的 AutomationPeer 向辅助技术公开。

只有具有值语义的控件才会公开 UI 自动化值。例如，TextBox 通过 TextBoxAutomationPeer 支持 IValueProvider，因此辅助技术可以检测和读取其当前值。

注释

如果您显式设置AutomationProperties.Name，请不要在名称中重复如“按钮”或“列表”这样的角色/类型术语。角色/类型来自 LocalizedControlType，许多辅助技术将其追加到名称。重复的角色文本可以生成类似于“按钮按钮”的输出。通过讲述人验证这个行为。

对 UI 自动化树视图的影响

UI 自动化表示三个树视图中的元素关系：原始视图、控件和内容。每个视图都有不同的用途。原始视图包括几乎所有自动化元素，控件视图强调交互式控件和结构导航点，内容视图侧重于传达面向用户的内容的元素。在实践中，辅助技术和辅助功能检查工具通常依赖于控制视图，因为它在完整性和可用性之间提供了最有用的平衡。

默认情况下，当应用通过 UI 自动化公开时，大多数控件派生元素将显示在控件视图中。在组合 UI 中，这可以引入重复或低值节点，为辅助技术用户添加干扰。使用 AutomationProperties.AccessibilityView 控制如何在树视图中公开特定元素。例如，在 Raw 中放置元素通常使其可用于诊断和遍历方案，同时将其从许多辅助技术使用的主要视图中排除。若要查看实际模式，请在 generic.xaml 中检查控件模板并搜索 AutomationProperties.AccessibilityView。

内文中的名称

许多 XAML 控件可以从 UI 中已可见的文本派生默认辅助名称。此行为减少了为基于文本的常见模式显式设置 AutomationProperties.Name 的需求，并帮助使用户听到的内容与他们所看到的内容保持一致。

TextBlock、 RichTextBlock 和 TextBox 通常将其文本内容提升为默认辅助名称。
ContentControl 子类评估其内容值，并使用迭代“ToString”策略提取默认可访问名称的字符串内容。

注释

UI 自动化对可访问名称强制实施 2048 个字符的最大限制。如果自动生成名称会生成较长的字符串，则该值将被截断。

图像的可访问名称

对于非文本内容（如图像和图表），请提供文本替代方法，以便屏幕阅读器能够正确识别和报出元素。由于这些元素通常不公开内部文本，因此 UI 自动化无法自动派生默认的辅助名称。（纯粹的装饰或结构视觉对象是一个例外，通常不应命名。需要宣布有意义的图像时，请显式设置 AutomationProperties.Name ，如以下示例所示。

<Image
    Source="Assets/product.png"
    AutomationProperties.Name="Customer using the product" />

或者，通过 AutomationProperties.LabeledBy 公开可见标题并将其关联到图像。这会使口语标签与屏幕文本保持一致，并避免在标记中复制字符串。以下 WinUI 示例显示了此模式：

<StackPanel Spacing="8">
    <Image
        x:Name="heroImage"
        Width="480"
        Source="Assets/snoqualmie-NF.jpg"
        AutomationProperties.LabeledBy="{Binding ElementName=heroCaption}" />
    <TextBlock x:Name="heroCaption" Text="Mount Snoqualmie Skiing" />
</StackPanel>

Label 和 LabeledBy

对于窗体字段，首选标记模式是在 TextBlock 中定义可见标签文本，并通过 AutomationProperties.LabeledBy 从输入控件引用该元素。这会在 UI 标签与自动化树中的控件之间建立关联，因此辅助技术可以报出与屏幕上显示的内容匹配的字段名称。这种模式通常比复制多个属性中的标签文本更易维护，因为相同的源字符串同时驱动视觉对象和可访问的标签。

<StackPanel x:Name="LayoutRoot" Spacing="12">
    <StackPanel Orientation="Horizontal" Spacing="8">
        <TextBlock x:Name="firstNameLabel" Text="First name" />
        <TextBox
            x:Name="firstNameTextBox"
            Width="180"
            AutomationProperties.LabeledBy="{Binding ElementName=firstNameLabel}" />
    </StackPanel>

    <StackPanel Orientation="Horizontal" Spacing="8">
        <TextBlock x:Name="lastNameLabel" Text="Last name" />
        <TextBox
            x:Name="lastNameTextBox"
            Width="180"
            AutomationProperties.LabeledBy="{Binding ElementName=lastNameLabel}" />
    </StackPanel>
</StackPanel>

辅助说明（可选的）

当仅无障碍名称不足时，无障碍说明提供有关 UI 元素的补充信息。使用它可添加阐明上下文，例如意向、使用提示或重要行为详细信息，帮助辅助技术用户了解如何使用控件。

在讲述人中，描述通常按需阅读，而不是作为默认公告的一部分。用户可以通过按 CapsLock+F 请求此附加详细信息。

将可访问名称视为控件的主要标识符，并使其保持简洁。如果需要更多说明，除了 AutomationProperties.Name 外，还通过 AutomationProperties.HelpText 提供额外详细信息。

提早并频繁测试可访问性

验证屏幕阅读器支持的最可靠方法是在开发期间直接使用屏幕阅读器测试应用，而不仅仅是在发布时。早期和重复的测试有助于在更改仍较便宜的时候识别缺失或误导性的辅助名称、不正确的控件暴露和导航问题。每次遍历后，根据用户实际听到的以及他们如何进行界面操作来改进 UI 结构和 UI 自动化属性。有关详细信息，请参阅辅助功能测试。

AccScope 是此工作流的有用工具，因为它将 UI 可视化为自动化树，从而更轻松地检查可以发现哪些辅助技术。它以讲述人为中心的视图可帮助你验证文本的源方式以及如何对元素进行分组和排序以便进行口语输出。在产品生命周期（包括早期设计和控制模板验证）中使用它，以便在用户测试前发现这些结构性可访问性问题。有关更多详细信息，请参阅 AccScope。

动态数据中的可访问名称

许多 Windows 控件通过 数据绑定呈现内容，这意味着辅助名称通常由运行时数据而不是静态 XAML 确定。当列表或项目模板被动态填充时，请确认在绑定完成后，每个生成的项目是否提供了一个有意义的可访问名称。根据控件和模板组合，可能需要通过编程设置或更新无障碍属性，以便自动化树反映最终呈现的状态。有关端到端示例，请参阅 XAML 辅助功能示例（存档的旧示例）中的“方案 4”。

可访问名称和本地化

可访问名称必须与可见的 UI 文本一样严格地进行本地化。在本地化资源中存储标签字符串，并通过 x：Uid 指令映射连接它们，因此口语输出与用户的语言匹配。如果显式设置 AutomationProperties.Name ，请确保值也来自本地化的资源，而不是硬编码的文本。

AutomationProperties 中的附加属性使用限定的资源键语法，以便本地化可以针对特定元素上的附加属性。例如，如果元素命名 MediumButton， 则 AutomationProperties.Name 的资源键为 MediumButton.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name。

反馈

此页面是否有帮助？

Last updated on 2026-03-26