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 或英语（美国）的“列表项”。 |
| UIA_NamePropertyId | 请参阅备注。 | 列表项控件的名称属性的值来自项的文本标签。 |
所需的控件模式
下表列出了所有列表项控件支持所需的 UI 自动化控件模式。 有关控件模式的详细信息，请参阅 UI 自动化控件模式概述。
| 控件模式 | 支持 | 笔记 |
|---|---|---|
| IExpandCollapseProvider | 取决于 | 如果可以作项来显示或隐藏信息，则必须实现 ExpandCollapse 控件模式。 |
| IGridItemProvider | 取决于 | 如果在列表容器中支持项到项空间导航，并且容器按行和列排列，则必须实现 GridItem 控件模式。 |
| IInvokeProvider | 取决于 | 如果项具有可以对其进行执行的命令，则独立于选择，则必须实现 调用 控件模式。 这通常是与双击列表项控件关联的作。 例如，从 Windows 资源管理器启动文档，或在 windows Media Player Microsoft中播放音乐文件。 |
| IScrollItemProvider | 取决于 | 如果列表项包含在可滚动的容器中，则必须实现 ScrollItem 控件模式。 |
| ISelectionItemProvider | 取决于 | 支持选择的列表项控件必须实现 SelectionItem 控件模式。 这允许列表项控件在选定时传达它们。 |
| IToggleProvider | 取决于 | 如果列表项可检查且作不执行选择状态更改，则必须实现 切换 控件模式。 |
| IValueProvider | 取决于 | 如果可以编辑项，则必须实现 值 控件模式。 对列表项控件的更改将导致更改 UIA_NamePropertyId 和 UIA_ValueValuePropertyId 属性的值。 |
必需事件
下表列出了列表项控件所需的 UI 自动化事件。 有关事件的详细信息，请参阅 UI 自动化事件概述。
| UI 自动化事件 | 笔记 |
|---|---|
| UIA_AutomationFocusChangedEventId | |
| UIA_BoundingRectanglePropertyId 属性更改事件。 | |
| UIA_ExpandCollapseExpandCollapseStatePropertyId 属性更改事件。 | 如果控件支持 ExpandCollapse 控件模式，则必须支持此事件。 |
| UIA_Invoke_InvokedEventId | 如果控件支持 调用 控件模式，则必须支持此事件。 |
| 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 属性更改事件。 | 如果控件支持 Toggle 控件模式，则必须支持此事件。 |
| UIA_ValueValuePropertyId 属性更改事件。 | 如果控件支持 值 控件模式，则它必须支持此事件。 |
言论
如果容器托管列表项，则导航的主要方式应转到列表项。 通过列表导航将焦点放在子元素上可能会令用户和辅助功能工具感到困惑。 如果容器承载项目垂直列表，则按向上键和向下键应浏览项，但按向右键和向左键可能会导航到焦点项的子元素，例如列表列或 UI 子元素。
相关主题