Benutzeroberflächenautomatisierungs-Eigenschaften für ClientsUI Automation Properties for Clients

Hinweis

Diese Dokumentation ist für .NET Framework-Entwickler vorgesehen, die die verwalteten BenutzeroberflächenautomatisierungUI Automation-Klassen verwenden möchten, die im System.Windows.Automation-Namespace definiert sind.This documentation is intended for .NET Framework developers who want to use the managed BenutzeroberflächenautomatisierungUI Automation classes defined in the System.Windows.Automation namespace. Die neuesten Informationen zu BenutzeroberflächenautomatisierungUI Automationfinden Sie unter Windows Automation-API: Automatisierungder Benutzeroberfläche.For the latest information about BenutzeroberflächenautomatisierungUI Automation, see Windows Automation API: UI Automation.

In dieser Übersicht werden BenutzeroberflächenautomatisierungUI Automation -Eigenschaften vorgestellt, die für Benutzeroberflächenautomatisierungs-Clientanwendungen verfügbar gemacht werden.This overview introduces you to BenutzeroberflächenautomatisierungUI Automation properties as they are exposed to UI Automation client applications.

Eigenschaften von AutomationElement -Objekten enthalten Informationen über Benutzeroberfläche (User Interface, UI)user interface (UI) -Elemente, in der Regel Steuerelemente.Properties on AutomationElement objects contain information about Benutzeroberfläche (User Interface, UI)user interface (UI) elements, usually controls. Die Eigenschaften eines AutomationElement sind generisch, das heißt, nicht spezifisch für einen Steuerelementtyp.The properties of an AutomationElement are generic; that is, not specific to a control type. Viele dieser Eigenschaften werden in der AutomationElement.AutomationElementInformation -Struktur verfügbar gemacht.Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.

Steuerelementmuster verfügen auch über Eigenschaften.Control patterns also have properties. Die Eigenschaften von Steuerelementmustern sind für das Muster spezifisch.The properties of control patterns are specific to the pattern. ScrollPattern enthält z. B. Eigenschaften, mit deren Hilfe eine Clientanwendung ermitteln kann, ob ein Fenster über vertikale oder horizontale Bildlaufleisten verfügt, und welche Ansichtsgrößen und Bildlaufpositionen aktuell verwendet werden.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. Steuerelementmuster machen alle Eigenschaften durch eine Struktur verfügbar, z. B. durch ScrollPattern.ScrollPatternInformation.Control patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.

BenutzeroberflächenautomatisierungUI Automation -Eigenschaften sind schreibgeschützt.properties are read-only. Um Eigenschaften eines Steuerelements festzulegen, müssen Sie die Methoden des entsprechenden Steuerelementmusters verwenden.To set properties of a control, you must use the methods of the appropriate control pattern. Verwenden Sie z. B. Scroll , um die Positionswerte eines Bildlauffensters zu ändern.For example, use Scroll to change the position values of a scrolling window.

Um die Leistung zu verbessern, können Eigenschaftswerte von Steuerelementen und Steuerelementmustern zwischengespeichert werden, wenn AutomationElement -Objekte abgerufen werden.To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. Weitere Informationen finden Sie unter Caching inBenutzeroberflächenautomatisierungs-Clients.For more information, see Caching in UI Automation Clients.

Eigenschaften-IDsProperty IDs

Eigenschafts Bezeichner (IDs) sind eindeutige, Konstante Werte, die in AutomationProperty -Objekten gekapselt sind.Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. Benutzeroberflächenautomatisierungs-Client Anwendungen erhalten diese AutomationElement IDs aus der-Klasse oder von der entsprechenden Steuerelement ScrollPatternMuster Klasse, z. b.UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. Benutzeroberflächenautomatisierungs-Anbieter rufen sie aus AutomationElementIdentifiers oder aus einer der Klassen von Steuerelementmuster-IDs ab, z. B. aus ScrollPatternIdentifiers.UI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.

Die numerische Id einer AutomationProperty wird von Anbietern zum Identifizieren von Eigenschaften verwendet, die in der IRawElementProviderSimple.GetPropertyValue -Methode abgefragt werden.The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. Im Allgemeinen müssen Clientanwendungen die Idnicht prüfen.In general, client applications do not need to examine the Id. Der ProgrammaticName wird nur zum Debuggen und für Diagnosezwecke verwendet.The ProgrammaticName is used only for debugging and diagnostic purposes.

EigenschaftsbedingungenProperty Conditions

Die Eigenschaften-IDs werden zum Erstellen PropertyCondition von Objekten verwendet, AutomationElement die zum Suchen von Objekten verwendet werden.The property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. Sie möchten z. B. ein AutomationElement mit einem bestimmten Namen oder alle aktivierten Steuerelemente suchen.For example, you might wish to find an AutomationElement that has a certain name, or all controls that are enabled. Jede PropertyCondition gibt eine AutomationProperty -ID und den Wert an, mit dem die Eigenschaft übereinstimmen muss.Each PropertyCondition specifies an AutomationProperty identifier and the value that the property must match.

Weitere Informationen finden Sie unter den folgenden Referenzthemen:For more information, see the following reference topics:

Abrufen von EigenschaftenRetrieving Properties

Einige Eigenschaften von AutomationElement und alle Eigenschaften einer Steuerelementmusterklasse werden als geschachtelte Eigenschaften der Current -Eigenschaft oder der Cached -Eigenschaft des AutomationElement oder des Steuerelementmusterobjekts verfügbar gemacht.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.

Darüber hinaus kann jedes AutomationElement oder jede Steuerelementmustereigenschaft, einschließlich von Eigenschaften, die in der Cached -Struktur oder in der Current -Struktur nicht verfügbar sind, mit einer der folgenden Methoden abgerufen werden: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:

Diese Methoden bieten eine etwas bessere Leistung sowie Zugriff auf sämtliche Eigenschaften.These methods offer slightly better performance as well as access to the full range of properties.

Im folgenden Codebeispiel werden die beiden Möglichkeiten zum Abrufen einer Eigenschaft eines AutomationElementveranschaulicht.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))

Um Eigenschaften von Steuerelementmustern abzurufen, die von AutomationElementunterstützt werden, muss das Steuerelementmusterobjekt nicht abgerufen werden.To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. Übergeben Sie einfach eine der Mustereigenschaften-IDs an die Methode.Simply pass one of the pattern property identifiers to the method.

Im folgenden Codebeispiel werden die beiden Möglichkeiten zum Abrufen einer Eigenschaft eines Steuerelementmusters veranschaulicht.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))

Die Get -Methoden geben ein Objectzurück.The Get methods return an Object. Die Anwendung muss das zurückgegebene Objekt in den richtigen Typ umwandeln, bevor der Wert verwendet wird.The application must cast the returned object to the proper type before using the value.

StandardeigenschaftswerteDefault Property Values

Wenn ein Benutzeroberflächenautomatisierungs-Anbieter eine Eigenschaft nicht implementiert, kann das BenutzeroberflächenautomatisierungUI Automation -System einen Standardwert bereitstellen.If a UI Automation provider does not implement a property, the BenutzeroberflächenautomatisierungUI Automation system is able to supply a default value. Wenn der Anbieter für ein Steuerelement die durch HelpTextPropertybezeichnete Eigenschaft z. B. nicht unterstützt, gibt BenutzeroberflächenautomatisierungUI Automation eine leere Zeichenfolge zurück.For example, if the provider for a control does not support the property identified by HelpTextProperty, BenutzeroberflächenautomatisierungUI Automation returns an empty string. Wenn der Anbieter die durch IsDockPatternAvailablePropertybezeichnete Eigenschaft nicht unterstützt, gibt BenutzeroberflächenautomatisierungUI Automation entsprechend falsezurück.Similarly, if the provider does not support the property identified by IsDockPatternAvailableProperty, BenutzeroberflächenautomatisierungUI Automation returns false.

Sie können dieses Verhalten ändern, indem Sie die AutomationElement.GetCachedPropertyValue -Methodenüberladung und die AutomationElement.GetCurrentPropertyValue -Methodenüberladung verwenden.You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. Wenn Sie true als zweiten Parameter angeben, gibt BenutzeroberflächenautomatisierungUI Automation keinen Standardwert zurück, sondern stattdessen den speziellen Wert NotSupported.When you specify true as the second parameter, BenutzeroberflächenautomatisierungUI Automation does not return a default value, but instead returns the special value NotSupported.

Mit dem folgenden Beispielcode wird versucht, eine Eigenschaft aus einem Element abzurufen. Wenn die Eigenschaft nicht unterstützt wird, wird stattdessen ein von der Anwendung definierter Wert verwendet.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)

Um zu ermitteln, welche Eigenschaften von einem Element unterstützt werden, verwenden Sie GetSupportedProperties.To discover what properties are supported by an element, use GetSupportedProperties. Dies gibt ein Array von AutomationProperty -IDs zurück.This returns an array of AutomationProperty identifiers.

Durch geänderte Eigenschaften ausgelöste EreignisseProperty-changed Events

Wenn sich ein Eigenschaftswert eines AutomationElement oder Steuerelementmusters ändert, wird ein Ereignis ausgelöst.When a property value on an AutomationElement or control pattern changes, an event is raised. Eine Anwendung kann solche Ereignisse abonnieren, indem AddAutomationPropertyChangedEventHandleraufgerufen wird, worin als letzter Parameter ein Array von AutomationProperty -IDs bereitgestellt wird, mit dem die betreffenden Eigenschaften angegeben werden.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.

Im AutomationPropertyChangedEventHandlerkönnen Sie die geänderte Eigenschaft ermitteln, indem Sie das Property -Element der Ereignisargumente überprüfen.In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. Die Argumente enthalten auch die alten und neuen Werte der geänderten BenutzeroberflächenautomatisierungUI Automation -Eigenschaft.The arguments also contain the old and new values of the BenutzeroberflächenautomatisierungUI Automation property that has changed. Diese Werte sind vom Typ Object und müssen in den richtigen Typ umgewandelt werden, bevor sie verwendet werden.These values are of type Object and must be cast to the correct type before being used.

Zusätzliche AutomationElement-EigenschaftenAdditional AutomationElement Properties

Neben der Current -Eigenschaftenstruktur und der Cached -Eigenschaftenstruktur besitzt AutomationElement die folgenden Eigenschaften, die über einfache Eigenschaftenaccessoren abgerufen werden.In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.

Die Eigenschaften-Property BeschreibungDescription
CachedChildren Eine Auflistung von untergeordneten AutomationElement -Objekten im Cache.A collection of child AutomationElement objects that are in the cache.
CachedParent Ein übergeordnetes AutomationElement -Objekt im Cache.An AutomationElement parent object that is in the cache.
FocusedElement (Statische Eigenschaft) Das AutomationElement , das den Eingabefokus besitzt.(Static property) The AutomationElement that has the input focus.
RootElement (Statische Eigenschaft) Das Stamm- AutomationElement.(Static property) The root AutomationElement.

Siehe auchSee also