客户端的 UI 自动化属性

项目
05/10/2023

备注

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

本概述为你介绍 UI 自动化属性，因为会向 UI 自动化客户端应用程序公开它们。

AutomationElement 对象上的属性包含有关用户界面 (UI) 元素（通常为控件）的信息。 AutomationElement 的属性为泛型；即，不特定于控件类型。其中的许多属性公开在 AutomationElement.AutomationElementInformation 结构中。

控件模式也有属性。控件模式的属性特定于该模式。例如， ScrollPattern 具有属性，该属性使客户端应用程序能够发现一个窗口是垂直可滚动还是水平可滚动，以及当前的视图大小和滚动位置。控件模式通过一种结构公开其所有属性，例如， ScrollPattern.ScrollPatternInformation。

UI 自动化属性是只读的。若要设置控件的属性，则必须使用相应的控件模式的方法。例如，使用 Scroll 更改滚动窗口的位置值。

若要提高性能，则当检索 AutomationElement 对象时可以缓存控件和控件模式的属性值。有关详细信息，请参阅缓存 UI 自动化客户端。

属性 ID

属性标识符 (ID) 是封装在 AutomationProperty 对象中的唯一常量值。 UI 自动化客户端应用程序从 AutomationElement 类或从相应的控件模式类（如 ScrollPattern ）获取这些 ID。 UI 自动化提供程序从 AutomationElementIdentifiers 或从其中一个控件模式标识符类（如 ScrollPatternIdentifiers）获取它们。

Id 的数值 AutomationProperty 被提供程序用于标识正在 IRawElementProviderSimple.GetPropertyValue 方法中进行查询的属性。一般情况下，客户端应用程序不需要检查 Id。ProgrammaticName 仅用于调试和诊断目的。

属性条件

属性 ID 用于构造用于查找 AutomationElement 对象的 PropertyCondition 对象。例如，你可能希望查找具有特定名称的 AutomationElement 或已启用的所有控件。每个 PropertyCondition 指定 AutomationProperty 标识符和属性必须匹配的值。

有关详细信息，请参阅以下参考主题：

检索属性

AutomationElement 的某些属性和控件模式类的所有属性都公开为 Current 的嵌套属性或 Cached 的 AutomationElement 属性或控件模式对象。

此外，任何 AutomationElement 或控件模式属性，包括在 Cached 或 Current 结构中不可用的属性，都可以通过使用以下方法之一进行检索：

这些方法提供略好的性能以及对属性的完整范围的访问权限。

下面的代码示例演示在 AutomationElement上检索属性的两种方法。

// elementList is an AutomationElement.

// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;

' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))

若要检索 AutomationElement支持的控件模式的属性，则不需要检索控件模式对象。只需将其中一个模式属性标识符传递给方法。

下面的代码示例演示在控件模式上检索属性的两种方法。

// elementList is an AutomationElement representing a list box.
// Error-checking is omitted. Assume that elementList is known to support SelectionPattern.

SelectionPattern selectPattern =
    elementList.GetCurrentPattern(SelectionPattern.Pattern) as SelectionPattern;
bool isMultipleSelect = selectPattern.Current.CanSelectMultiple;

// The following call is equivalent to the one above.
isMultipleSelect = (bool)
    elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty);

' elementList is an AutomationElement representing a list box.
' Error-checking is omitted. Assume that elementList is known to support SelectionPattern.
Dim selectPattern As SelectionPattern = _
    DirectCast(elementList.GetCurrentPattern(SelectionPattern.Pattern), SelectionPattern)
Dim isMultipleSelect As Boolean = selectPattern.Current.CanSelectMultiple

' The following call is equivalent to the one above.
isMultipleSelect = CBool(elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty))

Get 方法返回 Object。应用程序必须在使用值之前将返回的对象转换为正确的类型。

默认属性值

如果 UI 自动化提供程序不实现属性，则 UI 自动化系统能够提供一个默认值。例如，如果控件的提供程序不支持由 HelpTextProperty 标识的属性，则 UI 自动化会返回一个空字符串。同样，如果提供程序不支持由 IsDockPatternAvailableProperty 标识的属性，则 UI 自动化会返回 false。

你可以通过使用 AutomationElement.GetCachedPropertyValue 和 AutomationElement.GetCurrentPropertyValue 方法重载更改此行为。当指定 true 作为第二个参数时，UI 自动化不会返回默认值，而是返回特殊值 NotSupported。

下面的示例代码尝试从某个元素检索属性，如果该属性不受支持，将会改为使用应用程序定义的值。

// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
    help = "No help available";
}
string helpText = (string)help;

' elementList is an AutomationElement.
Dim help As Object = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, True)
If help Is AutomationElement.NotSupported Then
    help = "No help available"
End If
Dim helpText As String = CStr(help)

若要发现哪些属性受元素支持，请使用 GetSupportedProperties。这将返回 AutomationProperty 标识符的数组。

属性更改事件

当 AutomationElement 或控件模式上的属性值更改时，会引发一个事件。应用程序可以通过调用 AddAutomationPropertyChangedEventHandler订阅此类事件，提供 AutomationProperty 标识符的数组作为最后的参数以便指定相关属性。

在 AutomationPropertyChangedEventHandler中，你可以通过检查事件参数的 Property 成员来标识已更改的属性。这些参数还包含已更改的 UI 自动化属性的新旧值。这些值属于类型 Object ，并且必须在使用前转换为正确的类型。

其他 AutomationElement 属性

除 Current 和 Cached 属性结构以外， AutomationElement 还具有以下属性，它们是通过简单的属性访问器检索的。

属性	说明
CachedChildren	缓存中的子 AutomationElement 对象的集合。
CachedParent	缓存中的 AutomationElement 父对象。
FocusedElement	（静态属性）具有输入焦点的 AutomationElement 。
RootElement	（静态属性）根 AutomationElement。

通过