客户端的 UI 自动化属性

项目
08/12/2011

注意
本文档的目标读者是欲使用 System.Windows.Automation 命名空间中定义的托管 UI Automation类的 .NET Framework 开发人员。有关 UI Automation的最新信息，请参见 Windows Automation API: UI Automation（Windows 自动化 API：UI 自动化）。

本概述介绍向 UI 自动化客户端应用程序公开的 UI Automation属性。

AutomationElement 对象的属性包含有关 user interface (UI) 元素（通常是控件）的信息。 AutomationElement 的属性是泛型的，即，不特定于某个控件类型。其中的许多属性都在 AutomationElement.AutomationElementInformation 结构中公开。

控件模式也包含属性。控件模式的属性特定于模式。例如，ScrollPattern 的属性允许客户端应用程序发现窗口是可以垂直滚动还是水平滚动，以及当前的视图大小和滚动位置。控件模式通过某个结构（例如，ScrollPattern.ScrollPatternInformation）来公开其全部属性。

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

为了改进性能，可以在检索 AutomationElement 对象时缓存控件和控件模式的属性值。有关更多信息，请参见在 UI 自动化客户端中缓存。

本主题包括下列各节。

属性 ID
属性条件
检索属性
默认属性值
Property-changed 事件
其他 AutomationElement 属性
相关主题

属性 ID

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

提供程序使用 AutomationProperty 的数值 Id 来标识要在 IRawElementProviderSimple.GetPropertyValue 方法中查询的属性。通常，客户端应用程序无需检查 Id。 ProgrammaticName 仅用于调试和诊断目的。

属性条件

属性 IDs 用于构造 PropertyCondition 对象，这些对象可用来查找 AutomationElement 对象。例如，您可以查找使用特定名称的 AutomationElement，或已启用的所有控件。每个 PropertyCondition 都会指定一个 AutomationProperty 标识符以及该属性必须匹配的值。

有关更多信息，请参见下面的参考主题：

检索属性

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

另外，任何 AutomationElement 或控件模式属性（包括 Cached 或 Current 结构中不可用的属性）可通过下列方法之一来检索：

这些方法提供稍胜一畴的性能，以及提供对各个属性的访问权限。

下面的代码示例演示了两种针对 AutomationElement 检索属性的方法。

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

// elementList is an AutomationElement.

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

若要检索 AutomationElement 所支持的控件模式的属性，不必检索控件模式对象，而只需将某个模式属性标识符传递给该方法。

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

' 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))

// 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);

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

默认属性值

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

可以使用 AutomationElement.GetCachedPropertyValue 和 AutomationElement.GetCurrentPropertyValue 方法重载来更改此行为。如果将 true 指定为第二个参数，则 UI Automation不返回默认值，而是返回特殊值 NotSupported。

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

' 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)

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

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

Property-changed 事件

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

在 AutomationPropertyChangedEventHandler 中，可以通过检查事件参数的 Property 成员来标识已经更改的属性。这些参数还包含已发生更改的 UI Automation属性的旧值和新值。这些值的类型为 Object，在使用之前必须强制转换为正确的类型。

其他 AutomationElement 属性

AutomationElement 除了具有 Current 和 Cached 属性结构外，还具有下列可通过简单属性访问器检索的属性。

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

请参见

任务

订阅 UI 自动化事件

概念

在 UI 自动化客户端中缓存

服务器端 UI 自动化提供程序的实现

通过