列出控件类型

  • 项目

本主题提供有关 Microsoft UI 自动化对 List 控件类型的支持的信息。

List 控件类型提供了一种组织一个或多个平面组项的方法，并允许用户选择其中一个或多个项。 List 控件类型对它可能包含的子元素类型有宽松的限制。 这使 UI 自动化提供程序可以支持选择容器中的已知元素。

以下部分定义了列表控件类型所需的UI 自动化树结构、属性、控件模式和事件。 UI 自动化要求适用于 UI 框架/平台集成UI 自动化控件类型和控件模式支持的所有列表控件。

本主题包含以下各节：

典型树结构

下表描述了与列表控件相关的UI 自动化树的典型控件和内容视图，并描述了每个视图中可以包含的内容。 有关 UI 自动化树的详细信息，请参阅 UI 自动化树概述。

控件视图 内容视图
包含对应于控件的元素。 从树中删除冗余信息，以便辅助技术使用对最终用户有意义的最小信息集。
  • 列表
    • DataItem（0 个或多个）
    • ListItem（0 个或多个）
    • Group（0 个或多个）
    • ScrollBar（0 个、1 个或 2 个）
  • 列表
    • DataItem（0 个或多个）
    • ListItem（0 个或多个）
    • Group（0 个或多个）

实现 List 控件类型（如列表控件）的控件的控件视图组成如下：

  • 列表控件中的零个或多个项 (项可以基于 ListItem 或 DataItem 控件类型)
  • 列表控件中的零个或多个组控件
  • 零个、一个或两个滚动条控件

实现 List 控件类型（如列表控件）的控件的内容视图组成如下：

  • 列表控件中的零个或多个项 (项可以基于 ListItem 或 DataItem 控件类型)
  • 列表控件中的零个或多个组

列表控件不得具有除了组合在一起外的层次结构关系。 如果项在UI 自动化树中具有子级，则列表容器应基于 Tree 控件类型。

列表控件中可选择的项都可从列表控件的 UI 自动化树中的后代获取。 列表控件中的所有项都必须都属于同一个选择组。 列表中的可选项应公开为 ListItem (而不是 DataItem) 控件类型。

相关属性

下表列出了值或定义与 List 控件类型特别相关的UI 自动化属性。 有关UI 自动化属性的详细信息，请参阅从 UI 自动化 元素检索属性。

UI 自动化属性 值 说明
UIA_AutomationIdPropertyId 请参阅注释。 此属性的值在UI 自动化树的原始视图中的所有对等元素中必须是唯一的。
UIA_BoundingRectanglePropertyId 请参阅注释。 包含整个控件的最外层矩形。
UIA_ClickablePointPropertyId 请参阅注释。 如果列表控件具有一个可单击的点 (一个可单击的点，该点可以单击，使列表) 焦点，则必须通过此属性公开该点。 如果 UIA_IsOffscreenPropertyId 属性的值为 TRUE，则尝试检索此属性将导致 UIA_E_NOCLICKABLEPOINT 错误。
UIA_ControlTypePropertyId 列表
UIA_HelpTextPropertyId 请参阅注释。 列表控件的帮助文本应解释为什么要求用户从选项列表中进行选择。 例如，“从此列表中选择项将会设置显示监视器的分辨率。”
UIA_IsContentElementPropertyId TRUE 列表控件始终包含在 UI 自动化树的内容视图中。
UIA_IsControlElementPropertyId TRUE 列表控件始终包括在 UI 自动化树的控件视图中。
UIA_IsKeyboardFocusablePropertyId 请参阅注释。 如果该控件可以接收键盘焦点，则它必须支持此属性。
UIA_LabeledByPropertyId 请参阅注释。 如果存在静态文本标签，则此属性必须公开对该控件的引用。
UIA_LocalizedControlTypePropertyId 请参阅注释。 对应于 List 控件类型的本地化字符串。 en-US 或英语 (美国) 的默认值为“list”。
UIA_NamePropertyId 请参阅注释。 列表控件的 Name 属性的值应传达要求用户从中选择的选项类别。 此属性通常从静态文本标签获取其名称。 如果没有静态文本标签，则应用程序开发人员必须公开 Name 属性的值。
只有在另一个控件的子树内使用控件时，列表控件才不要求此属性。

所需的控件模式和属性

下表列出了所有列表控件需要支持的UI 自动化控件模式。 有关控件模式的详细信息，请参阅 UI Automation Control Patterns Overview。

控件模式/模式属性 支持/值 注释
IGridProvider 依赖的对象 当网格导航需要逐项可用时，实现 网格控件模式 。
IMultipleViewProvider 依赖的对象 如果控件可以支持容器中项的多个视图，则实现 MultipleView 控件模式。
IScrollProvider 依赖的对象 如果容器中的项可滚动，则实现 Scroll 控件模式。
ISelectionProvider 依赖的对象 如果控件支持支持选择的列表控件类型，则控件必须在 控件 中包含的项目之间保持选择状态时实现 Selection 控件模式。 如果控件中的项不可选择，则可以使用 Group 控件类型。
CanSelectMultiple 依赖的对象 List 控件可以是单选或多选容器。
IsSelectionRequired 依赖的对象 List 控件并不总是要求选择一个项。
ITableProvider 从不 列表控件类型从不支持 Table 控件模式。 如果控件需要支持此控件模式，则控件应基于 DataGrid 控件类型。

必需事件

下表列出了列表控件需要支持的UI 自动化事件。 有关事件的详细信息，请参阅 F:System.Windows.Automation.AutomationElementIdentifiers.IsEnabledProperty。

UI 自动化事件 说明
UIA_AutomationFocusChangedEventId
UIA_BoundingRectanglePropertyId 属性更改事件。
UIA_IsEnabledPropertyId 属性更改事件。 如果控件支持 IsEnabled 属性，则必须支持此事件。
UIA_IsOffscreenPropertyId 属性更改事件。 如果控件支持 IsOffscreen 属性，则必须支持此事件。
UIA_LayoutInvalidatedEventId 如果可以更改子项的布局，则控件必须支持此事件。
UIA_MultipleViewCurrentViewPropertyId 属性更改事件。 如果控件支持 MultipleView 控件模式，则必须支持此事件。
UIA_ScrollHorizontallyScrollablePropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_ScrollHorizontalScrollPercentPropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_ScrollHorizontalViewSizePropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_ScrollVerticalScrollPercentPropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_ScrollVerticallyScrollablePropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_ScrollVerticalViewSizePropertyId 属性更改事件。 如果控件支持 Scroll 控件模式，则必须支持此事件。
UIA_Selection_InvalidatedEventId 如果控件支持 Selection 控件模式，则必须支持此事件。
UIA_StructureChangedEventId

概念性

UI 自动化控件类型概述

UI 自动化概述