用戶端的UI自動化屬性

2025-06-17

備註

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

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

物件上的 AutomationElement 屬性包含使用者介面（UI）元素的相關信息，通常是控件。的屬性 AutomationElement 是泛型;也就是說，不是控件型別特有的。許多這些屬性在 AutomationElement.AutomationElementInformation 結構中公開。

控制件模式也有屬性。控制件模式的屬性是模式特有的。例如， ScrollPattern 具有可讓用戶端應用程式探索視窗是垂直還是可水平捲動的屬性，以及目前檢視大小和卷動位置為何。控件模式會透過結構公開其所有屬性;例如， ScrollPattern.ScrollPatternInformation。

使用者介面自動化屬性是唯讀的。若要設定控件的屬性，您必須使用適當控件模式的方法。例如，使用 Scroll 來變更捲動視窗的位置值。

為了提升效能，在擷取物件AutomationElement時，可以快取控件和控件模式的屬性值。如需詳細資訊，請參閱 UI 自動化客戶端中的快取。

屬性標識碼

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

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

物業條件

屬性標識碼用於建構 PropertyCondition 用來尋找 AutomationElement 物件的物件。例如，您可能希望尋找具有特定名稱的 AutomationElement，或者所有已啟用的控件。每個 PropertyCondition 都指定一個 AutomationProperty 識別碼，以及屬性必須相符的值。

如需詳細資訊，請參閱下列參考主題：

擷取屬性

AutomationElement 的某些屬性和控制模式類別的所有屬性，都會被公開為 Current 或控制模式物件的Cached或AutomationElement屬性中的巢狀屬性。

此外，任何AutomationElement或控件模式屬性，包括Cached或Current結構中無法使用的屬性，都可以使用以下其中一種方法來擷取：

這些方法不僅提供略微更好的效能，還能存取完整範圍的屬性。

以下程式碼範例顯示在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自動化提供者未實作屬性，則使用者介面自動化系統可以提供預設值。例如，如果控件的提供者不支援所 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 且必須先轉換成正確的類型，才能使用。

其他自動化元素屬性

除了 Current 和 Cached 屬性結構之外， AutomationElement 還有下列屬性，這些屬性是透過簡單屬性存取子擷取。

房產	說明
CachedChildren	快取中的子對象集合。
CachedParent	AutomationElement快取中的父物件。
FocusedElement	（靜態屬性）具有輸入焦點的AutomationElement。
RootElement	（靜態屬性）根 AutomationElement。

共用方式為