客户端的 UI 自动化属性UI Automation Properties for Clients

备注

本文档适用于想要使用 UI 自动化UI Automation 命名空间中定义的托管 System.Windows.Automation 类的 .NET Framework 开发人员。This documentation is intended for .NET Framework developers who want to use the managed UI 自动化UI Automation classes defined in the System.Windows.Automation namespace. 有关 UI 自动化UI Automation的最新信息,请参阅 Windows 自动化 API:UI 自动化For the latest information about UI 自动化UI Automation, see Windows Automation API: UI Automation.

本概述为你介绍 UI 自动化UI Automation 属性,因为会向 UI 自动化客户端应用程序公开它们。This overview introduces you to UI 自动化UI Automation properties as they are exposed to UI Automation client applications.

AutomationElement 对象上的属性包含有关 用户界面 (UI)user interface (UI) 元素(通常为控件)的信息。Properties on AutomationElement objects contain information about 用户界面 (UI)user interface (UI) elements, usually controls. AutomationElement 的属性为泛型;即,不特定于控件类型。The properties of an AutomationElement are generic; that is, not specific to a control type. 其中的许多属性公开在 AutomationElement.AutomationElementInformation 结构中。Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.

控件模式也有属性。Control patterns also have properties. 控件模式的属性特定于该模式。The properties of control patterns are specific to the pattern. 例如, ScrollPattern 具有属性,该属性使客户端应用程序能够发现一个窗口是垂直可滚动还是水平可滚动,以及当前的视图大小和滚动位置。For example, ScrollPattern has properties that enable a client application to discover whether a window is vertically or horizontally scrollable, and what the current view sizes and scroll positions are. 控件模式通过一种结构公开其所有属性,例如, ScrollPattern.ScrollPatternInformationControl patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.

UI 自动化UI Automation 属性是只读的。properties are read-only. 若要设置控件的属性,则必须使用相应的控件模式的方法。To set properties of a control, you must use the methods of the appropriate control pattern. 例如,使用 Scroll 更改滚动窗口的位置值。For example, use Scroll to change the position values of a scrolling window.

若要提高性能,则当检索 AutomationElement 对象时可以缓存控件和控件模式的属性值。To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. 有关详细信息,请参阅UI 自动化客户端中的缓存For more information, see Caching in UI Automation Clients.

属性 IDProperty IDs

属性标识符(Id)是封装在对象中的唯一常量值 AutomationPropertyProperty identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. UI 自动化客户端应用程序从 AutomationElement 类或从相应的控件模式类(如)获取这些 id ScrollPatternUI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. UI 自动化提供程序从 AutomationElementIdentifiers 或从其中一个控件模式标识符类(如 ScrollPatternIdentifiers)获取它们。UI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.

Id 的数值 AutomationProperty 被提供程序用于标识正在 IRawElementProviderSimple.GetPropertyValue 方法中进行查询的属性。The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. 通常情况下,客户端应用程序不需要检查 IdIn general, client applications do not need to examine the Id. ProgrammaticName 仅用于调试和诊断目的。The ProgrammaticName is used only for debugging and diagnostic purposes.

属性条件Property Conditions

属性 Id 用于构造 PropertyCondition 用于查找对象的对象 AutomationElementThe property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. 例如,你可能希望查找具有特定名称的 AutomationElement 或已启用的所有控件。For example, you might wish to find an AutomationElement that has a certain name, or all controls that are enabled. 每个 PropertyCondition 指定 AutomationProperty 标识符和属性必须匹配的值。Each PropertyCondition specifies an AutomationProperty identifier and the value that the property must match.

有关详细信息,请参阅以下参考主题:For more information, see the following reference topics:

检索属性Retrieving Properties

AutomationElement 的某些属性和控件模式类的所有属性都公开为 Current 的嵌套属性或 CachedAutomationElement 属性或控件模式对象。Some properties of AutomationElement and all properties of a control pattern class are exposed as nested properties of the Current or Cached property of the AutomationElement or control pattern object.

此外,任何 AutomationElement 或控件模式属性,包括在 CachedCurrent 结构中不可用的属性,都可以通过使用以下方法之一进行检索:In addition, any AutomationElement or control pattern property, including a property that is not available in the Cached or Current structure, can be retrieved by using one of the following methods:

这些方法提供略好的性能以及对属性的完整范围的访问权限。These methods offer slightly better performance as well as access to the full range of properties.

下面的代码示例演示在 AutomationElement上检索属性的两种方法。The following code example shows the two ways of retrieving a property on an 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支持的控件模式的属性,则不需要检索控件模式对象。To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. 只需将其中一个模式属性标识符传递给方法。Simply pass one of the pattern property identifiers to the method.

下面的代码示例演示在控件模式上检索属性的两种方法。The following code example shows the two ways of retrieving a property on a control pattern.

// 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 方法返回 ObjectThe Get methods return an Object. 应用程序必须在使用值之前将返回的对象转换为正确的类型。The application must cast the returned object to the proper type before using the value.

默认属性值Default Property Values

如果 UI 自动化提供程序不实现属性,则 UI 自动化UI Automation 系统能够提供一个默认值。If a UI Automation provider does not implement a property, the UI 自动化UI Automation system is able to supply a default value. 例如,如果控件的提供程序不支持由 HelpTextProperty标识的属性,则 UI 自动化UI Automation 返回一个空字符串。For example, if the provider for a control does not support the property identified by HelpTextProperty, UI 自动化UI Automation returns an empty string. 同样,如果提供程序不支持由 IsDockPatternAvailableProperty标识的属性,则 UI 自动化UI Automation 返回 falseSimilarly, if the provider does not support the property identified by IsDockPatternAvailableProperty, UI 自动化UI Automation returns false.

你可以通过使用 AutomationElement.GetCachedPropertyValueAutomationElement.GetCurrentPropertyValue 方法重载更改此行为。You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. 当指定 true 作为第二个参数时, UI 自动化UI Automation 不返回默认值,而是返回特殊值 NotSupportedWhen you specify true as the second parameter, UI 自动化UI Automation does not return a default value, but instead returns the special value NotSupported.

下面的示例代码尝试从某个元素检索属性,如果该属性不受支持,将会改为使用应用程序定义的值。The following example code attempts to retrieve a property from an element, and if the property is not supported, an application-defined value is used instead.

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

若要发现哪些属性受元素支持,请使用 GetSupportedPropertiesTo discover what properties are supported by an element, use GetSupportedProperties. 这将返回 AutomationProperty 标识符的数组。This returns an array of AutomationProperty identifiers.

属性更改事件Property-changed Events

AutomationElement 或控件模式上的属性值更改时,会引发一个事件。When a property value on an AutomationElement or control pattern changes, an event is raised. 应用程序可以通过调用 AddAutomationPropertyChangedEventHandler订阅此类事件,提供 AutomationProperty 标识符的数组作为最后的参数以便指定相关属性。An application can subscribe to such events by calling AddAutomationPropertyChangedEventHandler, supplying an array of AutomationProperty identifiers as the last parameter in order to specify the properties of interest.

AutomationPropertyChangedEventHandler中,你可以通过检查事件参数的 Property 成员来标识已更改的属性。In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. 这些参数还包含已更改的 UI 自动化UI Automation 属性的新旧值。The arguments also contain the old and new values of the UI 自动化UI Automation property that has changed. 这些值属于类型 Object ,并且必须在使用前转换为正确的类型。These values are of type Object and must be cast to the correct type before being used.

其他 AutomationElement 属性Additional AutomationElement Properties

CurrentCached 属性结构以外, AutomationElement 还具有以下属性,它们是通过简单的属性访问器检索的。In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.

属性Property 说明Description
CachedChildren 缓存中的子 AutomationElement 对象的集合。A collection of child AutomationElement objects that are in the cache.
CachedParent 缓存中的 AutomationElement 父对象。An AutomationElement parent object that is in the cache.
FocusedElement (静态属性)具有输入焦点的 AutomationElement(Static property) The AutomationElement that has the input focus.
RootElement (静态属性)根 AutomationElement(Static property) The root AutomationElement.

另请参阅See also