共用方式為

用戶端的 UI 自動化屬性

  • 發行項
注意事項注意事項

這份文件適用於想要使用 System.Windows.Automation 命名空間中定義之 Managed UI Automation 類別的 .NET Framework 開發人員。如需 UI Automation 的最新資訊，請參閱 Windows Automation API：使用者介面自動化 (英文)。

本概觀簡介公開至 UI 自動用戶端應用程式的 UI Automation屬性。

AutomationElement 物件上的屬性含有關於user interface (UI) 項目 (通常是控制項) 的資訊。 AutomationElement 的屬性是泛型屬性，也就是說，不是控制項型別特有的。 許多這些屬性都會在 AutomationElement.AutomationElementInformation 結構中公開。

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

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

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

這個主題包含下列章節。

  • 屬性 ID
  • 屬性條件
  • 擷取屬性
  • 預設屬性值
  • 屬性變更事件
  • 其他 AutomationElement 屬性
  • 相關主題

屬性 ID

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

提供者會使用 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 識別項的陣列。

屬性變更事件

當 AutomationElement 或控制項模式上的屬性值變更時，會引發事件。 應用程式可以藉由呼叫 AddAutomationPropertyChangedEventHandler 來訂閱這種事件，並提供 AutomationProperty 識別項的陣列做為最後一個參數，以指定想要的屬性。

在 AutomationPropertyChangedEventHandler 中，您可以檢查事件引數的 Property 成員，藉以識別已變更的屬性。 這些引數也會包含已變更之 UI Automation屬性的新舊值。 這些值屬於型別 Object，在使用之前，必須先轉型為正確的型別。

其他 AutomationElement 屬性

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

屬性

說明

CachedChildren

快取中 AutomationElement 子物件的集合。

CachedParent

快取中的 AutomationElement 父物件。

FocusedElement

(靜態屬性) 具有輸入焦點的 AutomationElement。

RootElement

(靜態屬性) 根 AutomationElement。

請參閱

工作

訂閱 UI 自動化事件

概念

UI 自動化用戶端中的快取

伺服器端 UI 自動化提供者實作