用戶端的 UI 自動化屬性UI Automation Properties for Clients

注意

這份文件適用於想要使用 System.Windows.Automation 命名空間中定義之 Managed UI 自動化UI 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 Automation API:使用者介面自動化。For the latest information about UI 自動化UI Automation, see Windows Automation API: UI Automation.

本概觀向您介紹公開至使用者介面自動化用戶端應用程式的 UI 自動化UI Automation 屬性。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.

屬性識別碼Property IDs

屬性識別碼(id)是封裝在物件中AutomationProperty的唯一、常數值。Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. 使用者介面自動化用戶端應用程式會從AutomationElement類別或適當的控制項模式類別( ScrollPattern例如)取得這些識別碼。UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. 使用者介面自動化提供者從 AutomationElementIdentifiers 取得這些,或是從控制項模式識別項類別的其中一項取得,例如 ScrollPatternIdentifiersUI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.

提供者使用 IdAutomationProperty 數值來識別在 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

屬性識別碼是用來建立PropertyCondition用來尋找AutomationElement物件的物件。The 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 的巢狀屬性或 Cached 或控制項模式物件的 AutomationElement 屬性。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 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