用戶端的 UI 自動化屬性

注意

本文件適用對象為 .NET Framework 開發人員，其想要使用 System.Windows.Automation 命名空間中定義的受控 UI 自動化類別。 如需 UI 自動化的最新資訊，請參閱 Windows 自動化 API：UI 自動化。

此概觀會介紹 UI 自動化屬性，這些屬性會公開給 UI 自動化用戶端應用程式。

AutomationElement 物件的屬性包含使用者介面 (UI) 元素的相關資訊，通常是控制項。 AutomationElement 的屬性是泛型；也就是不專屬於某個控制項類型。 這些屬性有許多公開於 AutomationElement.AutomationElementInformation 結構。

控制項模式也有屬性。 控制項模式的屬性專屬於此模式。 例如， ScrollPattern 的屬性可以讓用戶端運用程式來探索視窗是可以垂直或水平捲動，以及目前檢視大小和捲動位置。 控制項模式透過結構公開其所有屬性；例如， ScrollPattern.ScrollPatternInformation。

UI 自動化屬性為唯讀資訊。 若要設定控制項的屬性，您必須使用適當控制項模式的方法。 例如，使用 Scroll 來變更捲動中視窗的位置值。

若要改善效能，擷取 AutomationElement 物件時，可以快取控制項和控制項模式的屬性值。 如需詳細資訊，請參閱 UI 自動化用戶端的快取。

屬性識別碼

屬性識別碼 (ID) 是封裝在 AutomationProperty 物件內的唯一常數值。 UI 自動化用戶端應用程式會從 AutomationElement 類別或從適當的控制項模式類別取得這些識別碼，例如 ScrollPattern。 使用者介面自動化提供者從 AutomationElementIdentifiers 取得這些，或是從控制項模式識別項類別的其中一項取得，例如 ScrollPatternIdentifiers。

提供者使用 Id 的 AutomationProperty 數值來識別在 IRawElementProviderSimple.GetPropertyValue 方法中要查詢的屬性。 一般而言，用戶端應用程式不需要檢查 Id。ProgrammaticName 僅供偵錯和診斷之用。

屬性條件

屬性識別碼用於建構用來尋找 AutomationElement 物件的 PropertyCondition 物件。 例如，您要尋找有特定名稱的 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 具有下列屬性，這會透過簡單的屬性存取子擷取。

屬性	說明
CachedChildren	快取中的子 AutomationElement 物件集合。
CachedParent	快取中的 AutomationElement 父物件。
FocusedElement	(靜態屬性) 具有輸入焦點的 AutomationElement 。
RootElement	(靜態屬性) 根 AutomationElement。

另請參閱

• UI 自動化用戶端中的快取
• 伺服器端 UI 自動化提供者實作
• 訂閱 UI 自動化事件