DataItem 控件类型

项目
06/13/2023

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

联系人列表中的条目是数据项控件的一个示例。数据项控件包含最终用户感兴趣的信息。它比简单列表项更复杂，因为它包含更丰富的信息。

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

本主题包含以下各节：

典型树结构
相关属性
所需的控件模式
在大型列表中使用 DataItems
必需事件
DataItem 控件类型示例
相关主题

典型树结构

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

控件视图	内容视图
DataItem 不定（0 或更多；可以在层次结构中构建）	DataItem 不定（0 或更多；可以在层次结构中构建）

在数据网格中的数据项元素可以承载各种对象，包括另一层数据项或特定的网格元素（如文本、图像或编辑控件）。如果数据项元素具有特定的对象角色，则应将元素公开为特定的控件类型;例如，网格中可选数据项的 ListItem 控件类型。

相关属性

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

UI 自动化属性	值	说明
UIA_AutomationIdPropertyId	请参阅注释。	此属性的值在UI 自动化树的原始视图中的所有对等元素中必须是唯一的。
UIA_BoundingRectanglePropertyId	请参阅注释。	包含整个控件的最外层矩形。
UIA_ClickablePointPropertyId	请参阅注释。	如果存在边界矩形，则受支持。如果边界矩形中的每个点都不可单击，并且元素执行专门的命中测试，请重写并提供一个可单击的点。
UIA_ControlTypePropertyId	DataItem
UIA_IsContentElementPropertyId	TRUE	数据项控件必须始终为内容。
UIA_IsControlElementPropertyId	TRUE	数据项控件必须始终为控件。
UIA_IsKeyboardFocusablePropertyId	请参阅注释。	如果该控件可以接收键盘焦点，则它必须支持此属性。
UIA_ItemStatusPropertyId	请参阅注释。	如果控件包含正在动态更新的状态，则必须支持此属性，以便辅助技术可以在元素的状态更改时接收更新。
UIA_ItemTypePropertyId	请参阅注释。	这是将项所表示的基础对象传达给最终用户的字符串值。示例包括“媒体文件”和“联系人”。
UIA_LabeledByPropertyId	Null	数据项控件不具有静态文本标签。
UIA_LocalizedControlTypePropertyId	请参阅注释。	对应于 DataItem 控件类型的本地化字符串。 en-US 或英语 (美国) 的默认值为“data item”。
UIA_NamePropertyId	请参阅注释。	数据项控件始终包含用户可识别为项标识符的主要文本元素。

所需的控件模式

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

控件模式	支持	说明
IExpandCollapseProvider	依赖的对象	如果可以展开或折叠数据项以显示和隐藏信息，则必须支持 ExpandCollapse 控件模式。
IGridItemProvider	依赖的对象	当数据项集合在容器中可用时，数据项将支持 GridItem 控件模式，该集合可在空间上导航项到项。
IScrollItemProvider	依赖的对象	当所有数据项的数据容器包含的项数超过屏幕可容纳的项数时，都支持使用 ScrollItem 控件模式滚动到视图中的功能。
ISelectionItemProvider	依赖的对象	选择数据项的能力取决于内容。
ITableItemProvider	依赖的对象	如果数据项包含在具有标头元素的 DataGrid 控件类型中，则它应支持 TableItem 控件模式。
IToggleProvider	依赖的对象	如果数据项包含可循环访问的状态，则它应支持切换控件模式。
IValueProvider	依赖的对象	如果数据项的主文本是可编辑的，则必须支持 Value 控件模式。

在大型列表中使用 DataItems

由于大型列表通常在 UI 框架中虚拟化以帮助提高性能，因此UI 自动化客户端无法使用UI 自动化查询功能以与其他项容器中相同的方式搜索完整树的内容。客户端应将项滚动到视图 (或展开控件以显示所有可用选项) ，然后再从数据项访问完整的信息集。

在数据项的 UI 自动化元素上调用 SetFocus 时，Microsoft Windows 资源管理器将成功返回，并导致焦点设置为数据项子树中的“编辑”控件。

必需事件

下表列出了数据项控件需要支持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 控件模式，则它必须支持此事件。