ListItem 控件类型
本主题提供有关 Microsoft UI 自动化对 ListItem 控件类型的支持的信息。
列表项控件是实现 ListItem 控件类型的控件的示例。
以下部分定义了 ListItem 控件类型所需的UI 自动化树结构、属性、控件模式和事件。 UI 自动化要求适用于 UI 框架/平台集成UI 自动化控件类型和控件模式支持的所有列表项控件。
本主题包含以下各节：
典型树结构
下表描述了与列表项控件相关的UI 自动化树的典型控件和内容视图，并描述了每个视图中可以包含的内容。 有关 UI 自动化树的详细信息，请参阅 UI 自动化树概述。
| 控件视图 | 内容视图 |
|---|---|
|
|
UI 自动化树的内容视图中列表项控件的子级必须始终显示零个子级。 如果控件的结构使其他项包含在列表项下方，则它应遵循对 TreeItem 控件类型的UI 自动化支持的要求。
相关属性
下表列出了值或定义与 ListItem 控件类型特别相关的UI 自动化属性。 有关UI 自动化属性的详细信息，请参阅从 UI 自动化 元素检索属性。
| UI 自动化属性 | 值 | 说明 |
|---|---|---|
| UIA_AutomationIdPropertyId | 请参阅注释。 | 此属性的值在UI 自动化树的原始视图中的所有对等元素中必须是唯一的。 如果已知该元素在用户界面的不同实例之间保持一致，请为列表项分配 AutomationId 属性。 如果列表项已动态填充且不可预测，请将 AutomationId 属性留空。 |
| UIA_BoundingRectanglePropertyId | 请参阅注释。 | 此属性的此值应包括图像的区域和列表项的文本内容。 |
| UIA_ClickablePointPropertyId | 依赖的对象 | 如果列表控件具有一个可单击的点 (一个可单击的点，该点可以单击，使列表) 焦点，则必须通过此属性公开该点。 如果列表控件完全由子级列表项覆盖，它将返回 UIA_E_NOCLICKABLEPOINT 错误，指示客户端必须请求列表控件内的项以获取可单击点。 |
| UIA_ControlTypePropertyId | ListItem | 此值对于所有 UI 框架均相同。 |
| UIA_HelpTextPropertyId | 请参阅注释。 | 列表控件的帮助文本应说明为什么要求用户从选项列表中进行选择，帮助文本内容与工具提示所示的信息通常为同一类型。 例如，“选择一项以设置监视器的显示分辨率”。 |
| UIA_IsContentElementPropertyId | TRUE | 列表控件始终包含在 UI 自动化树的内容视图中。 |
| UIA_IsControlElementPropertyId | TRUE | 列表控件始终包括在 UI 自动化树的控件视图中。 |
| UIA_IsKeyboardFocusablePropertyId | 请参阅注释。 | 如果容器可以接受键盘输入，则此属性值应为 TRUE。 |
| UIA_IsOffscreenPropertyId | 依赖的对象 | 此属性必须返回一个值，该值指示列表项当前是否滚动到实现 Scroll 控件模式的父容器中的视图。 |
| UIA_ItemStatusPropertyId | 依赖的对象 | 如果控件包含动态更新的状态，则必须支持此属性，以便辅助技术可以在元素的状态更改时接收更新。 |
| UIA_ItemTypePropertyId | 依赖的对象 | 此属性应为表示基础对象的列表项控件公开。 这些列表项控件通常有一个与控件关联的图标，用户将该控件与基础对象相关联。 |
| UIA_LabeledByPropertyId | 请参阅注释。 | 如果存在静态文本标签，则此属性必须公开对该控件的引用。 |
| UIA_LocalizedControlTypePropertyId | 请参阅注释。 | 与 ListItem 控件类型对应的本地化字符串。 en-US 或英语 (美国) 的默认值为“list item”。 |
| UIA_NamePropertyId | 请参阅注释。 | 列表项控件的 name 属性的值来自项的文本标签。 |
所需的控件模式
下表列出了所有列表项控件所需的UI 自动化控件模式。 有关控件模式的详细信息，请参阅 UI Automation Control Patterns Overview。
| 控件模式 | 支持 | 说明 |
|---|---|---|
| IExpandCollapseProvider | 依赖的对象 | 如果可以操作项以显示或隐藏信息，则必须实现 ExpandCollapse 控件模式。 |
| IGridItemProvider | 依赖的对象 | 如果列表容器中支持项到项的空间导航，并且容器按行和列排列，则必须实现 GridItem 控件模式。 |
| IInvokeProvider | 依赖的对象 | 如果项具有可对其进行执行的命令（独立于选择），则必须实现 Invoke 控件模式。 这通常是与双击列表项控件相关联的操作。 示例包括从 Windows 资源管理器启动文档，或在 Microsoft Windows 媒体播放器中播放音乐文件。 |
| IScrollItemProvider | 依赖的对象 | 如果列表项包含在可滚动的容器中，则必须实现 ScrollItem 控件模式。 |
| ISelectionItemProvider | 依赖的对象 | 支持选择的列表项控件必须实现 SelectionItem 控件模式。 这允许列表项控件传达它们被选中的时间。 |
| IToggleProvider | 依赖的对象 | 如果列表项是可检查的，并且操作不执行选择状态更改，则必须实现 切换 控件模式。 |
| IValueProvider | 依赖的对象 | 如果可以编辑该项，则必须实现 Value 控件模式。 对列表项控件的更改将导致 更改UIA_NamePropertyId 和 UIA_ValueValuePropertyId 属性的值。 |
必需事件
下表列出了列表项控件需要支持的UI 自动化事件。 有关事件的详细信息，请参阅 F:System.Windows.Automation.AutomationElementIdentifiers.IsEnabledProperty。
| UI 自动化事件 | 说明 |
|---|---|
| UIA_AutomationFocusChangedEventId | |
| UIA_BoundingRectanglePropertyId 属性更改事件。 | |
| UIA_ExpandCollapseExpandCollapseStatePropertyId 属性更改事件。 | 如果控件支持 ExpandCollapse 控件模式，则它必须支持此事件。 |
| UIA_Invoke_InvokedEventId | 如果控件支持 Invoke 控件模式，则必须支持此事件。 |
| UIA_IsEnabledPropertyId 属性更改事件。 | 如果控件支持 IsEnabled 属性，它必须支持此事件。 |
| UIA_IsOffscreenPropertyId 属性更改事件。 | 如果控件支持 IsOffscreen 属性，则必须支持此事件。 |
| UIA_ItemStatusPropertyId 属性更改事件。 | 如果 控件支持 ItemStatus 属性，则 必须支持此事件。 |
| UIA_NamePropertyId 属性更改事件。 | |
| UIA_SelectionItem_ElementAddedToSelectionEventId | 如果控件支持 SelectionItem 控件模式，则必须支持此事件。 |
| UIA_SelectionItem_ElementRemovedFromSelectionEventId | 如果控件支持 SelectionItem 控件模式，则必须支持此事件。 |
| UIA_SelectionItem_ElementSelectedEventId | 如果控件支持 SelectionItem 控件模式，则必须支持此事件。 |
| UIA_StructureChangedEventId | |
| UIA_ToggleToggleStatePropertyId 属性更改事件。 | 如果控件支持 切换 控件模式，则它必须支持此事件。 |
| UIA_ValueValuePropertyId 属性更改事件。 | 如果控件支持 Value 控件模式，则它必须支持此事件。 |
备注
如果容器承载列表项，则导航的主要方式应转到列表项。 通过列表导航将焦点放在子元素上可能会让用户和辅助功能工具感到困惑。 如果容器承载一个垂直项列表，则按向上键和向下键应在项中导航，但按向右键和向左键可能会导航到重点项的子元素，例如列表列或 UI 子元素。
相关主题
-
概念性