客户端的 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 用于构造用于查找 PropertyCondition 对象的 AutomationElement 对象。 例如，你可能希望找到具有特定名称的AutomationElement，或者找到所有已启用的控件。 每个 PropertyCondition 属性都指定一个 AutomationProperty 标识符和属性必须匹配的值。

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

• FindFirst

• FindAll

• Condition

检索属性

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

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

• GetCachedPropertyValue

• GetCurrentPropertyValue

这些方法不仅提供稍微更好的性能，还可以全面访问所有属性。

下面的代码示例展示了在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还具有以下属性，这些属性可以通过简单的访问器进行检索。

另请参阅

• UI 自动化客户端中的缓存
• Server-Side 自动化用户界面提供程序实现
• 订阅 UI 自动化事件