UI 自动化对 DataGrid 控件类型的支持

项目
05/10/2023

备注

本文档适用于想要使用 System.Windows.Automation 命名空间中定义的托管 UI 自动化类的 .NET Framework 开发人员。有关 UI 自动化的最新信息，请参阅 Windows 自动化 API：UI 自动化。

本主题介绍 Microsoft UI 自动化对于 DataGrid 控件类型的支持信息。在 UI 自动化中，控件类型是一组条件，控件必须满足这些条件才能使用 ControlType 属性。这些条件包括针对 UI 自动化树结构、UI 自动化属性值和控件模式的特定准则。

利用 DataGrid 控件类型，用户可以轻松地处理包含列中所显示元数据的项。数据网格控件在行中显示项，在列中显示有关这些项的信息。 Microsoft Vista 资源管理器中的列表视图控件就是支持 DataGrid 控件类型的示例。

以下几部分定义 DataGrid 控件类型必需的 UI 自动化树结构、属性、控件模式和事件。 UI 自动化要求适用于所有数据网格控件，无论 Windows Presentation Foundation (WPF)、Win32 还是 Windows 窗体。

必需的 UI 自动化树结构

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

UI 自动化树 - 控件视图	UI 自动化树 - 内容视图
DataGrid 标头（0 个、1 个或 2 个） HeaderItem（列数或行数） DataItem（0 个或更多；可采用层次结构的形式构成）	DataGrid - DataItem（0 个或更多；可采用层次结构的形式构成）

必需的 UI 自动化属性

下表列出了值或定义与数据网格控件密切相关的属性。有关 UI 自动化属性的详细信息，请参阅客户端的 UI 自动化属性。

属性	值	说明
AutomationIdProperty	请参阅注释。	此属性的值在应用程序的所有控件中都必须保持唯一。
BoundingRectangleProperty	请参阅注释。	包含整个控件的最外层矩形。
ClickablePointProperty	请参阅注释。	如果存在边界矩形，则受支持。如果边界矩形中存在无法单击的点，而你要执行专门的命中测试，则重写并提供可单击的点。
ControlTypeProperty	DataGrid	此值对于所有 UI 框架均相同。
IsContentElementProperty	正确	此属性的值必须始终为 True。这意味着数据网格控件必须始终位于 UI 自动化树的内容视图中。
IsControlElementProperty	正确	此属性的值必须始终为 True。这意味着数据网格控件必须始终位于 UI 自动化树的控件视图中。
IsKeyboardFocusableProperty	请参阅注释。	如果该控件可以接收键盘焦点，则它必须支持此属性。
LabeledByProperty	请参阅注释。	如果存在静态文本标签，则此属性必须公开对该控件的引用。
LocalizedControlTypeProperty	“数据网格”	与 DataGrid 控件类型相对应的本地化字符串。
NameProperty	请参阅注释。	数据网格控件通常从静态文本标签中获取其 `Name` 属性的值。如果没有静态文本标签，则应用程序开发人员必须为 `Name` 属性赋值。 `Name` 属性的值决不应该是编辑控件的文本内容。

必需的 UI 自动化控件模式

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

控件模式	支持	说明
IGridProvider	是	数据网格控件本身始终支持 Grid 控件模式，因为它包含的项具有放置在网格中的元数据。
IScrollProvider	依赖的对象	是否能够滚动数据网格取决于内容以及滚动条是否存在。
ISelectionProvider	依赖的对象	能否选择数据网格取决于内容。
ITableProvider	是	数据网格控件的子树内始终有标题，因此必须支持 Table 控件模式。

数据网格容器内的数据项至少将支持：

Selection Item 控件模式（如果数据网格是可选择的）
Scroll Item 控件模式（如果数据网格是可滚动的）
Grid Item 控件模式
Table Item 控件模式

必需的 UI 自动化事件

下表列出了需要由所有数据网格控件支持的 UI 自动化事件。有关事件的详细信息，请参阅 UI Automation Events Overview。

UI 自动化事件	支持	说明
AutomationFocusChangedEvent	必须	无
BoundingRectangleProperty 属性更改事件。	必需	无
IsEnabledProperty 属性更改事件。	必需	无
IsOffscreenProperty 属性更改事件。	必需	无
LayoutInvalidatedEvent	依赖的对象	无
StructureChangedEvent	必须	无
CurrentViewProperty 属性更改事件。	依赖的对象	无
HorizontallyScrollableProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
HorizontalScrollPercentProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
HorizontalViewSizeProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
VerticalScrollPercentProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
VerticallyScrollableProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
VerticalViewSizeProperty 属性更改事件。	依赖的对象	如果控件支持 Scroll 模式，则它必须支持此事件。
InvalidatedEvent	必需	无

Date Grid 控件类型示例

下图阐释了实现 DataGrid 控件类型的列表视图控件。

Graphic of a List View control with two data items

与列表视图控件相关的 UI 自动化树的控件视图和内容视图如下所示。每个自动化元素的控件模式均显示在括号中。

UI 自动化树 - 控件视图	UI 自动化树 - 内容视图
DataGrid（Table、Grid、Selection）标头 HeaderItem“名称”(Invoke) HeaderItem“修改日期” (Invoke) HeaderItem“大小” (Invoke) Group“Contoso”（TableItem、GridItem、SelectionItem、Table、Grid） DataItem“Accounts Receivable.doc”（SelectionItem、Invoke、TableItem、GridItem） DataItem“Accounts Payable.doc”（SelectionItem、Invoke、TableItem、GridItem）	DataGrid（Table、Grid、Selection） Group“Contoso”（TableItem、GridItem、SelectionItem、Table、Grid） DataItem“Accounts Receivable.doc”（SelectionItem、Invoke、TableItem、GridItem） DataItem“Accounts Payable.doc”（SelectionItem、Invoke、TableItem、GridItem）

UI 自动化树 - 控件视图

UI 自动化树 - 内容视图

DataGrid（Table、Grid、Selection）
标头
- HeaderItem“名称”(Invoke)
- HeaderItem“修改日期” (Invoke)
- HeaderItem“大小” (Invoke)
Group“Contoso”（TableItem、GridItem、SelectionItem、Table*、Grid*）
- DataItem“Accounts Receivable.doc”（SelectionItem、Invoke、TableItem*、GridItem*）
- DataItem“Accounts Payable.doc”（SelectionItem、Invoke、TableItem*、GridItem*）

DataGrid（Table、Grid、Selection）
Group“Contoso”（TableItem、GridItem、SelectionItem、Table*、Grid*）
- DataItem“Accounts Receivable.doc”（SelectionItem、Invoke、TableItem*、GridItem*）
- DataItem“Accounts Payable.doc”（SelectionItem、Invoke、TableItem*、GridItem*）

* 上面的示例显示了包含多个控件级别的 DataGrid。 Group（“Contoso”）控件包含两个 DataItem 控件（“Accounts Receivable.doc”和“Accounts Payable.doc”）。 DataGrid/GridItem 对不依赖于其他级别的对。 Group 下的 DataItem 控件还能以 ListItem 控件类型公开，使它们能够更清楚地呈现为可选择的对象，而不是简单的数据元素。此示例不包括分组数据项的子元素。