Propriétés d'UI Automation pour les clients

2025-06-20

Remarque

Cette documentation est destinée aux développeurs .NET Framework qui souhaitent utiliser les classes UI Automation managées définies dans l’espace de noms System.Windows.Automation. Pour obtenir les informations les plus récentes sur UI Automation, consultez API Windows Automation : UI Automation.

Cette vue d’ensemble vous présente les propriétés UI Automation, car elles sont exposées aux applications clientes UI Automation.

Les propriétés sur AutomationElement les objets contiennent des informations sur les éléments d’interface utilisateur, généralement des contrôles. Les propriétés d’un AutomationElement sont génériques ; c’est-à-dire non spécifiques à un type de contrôle. La plupart de ces propriétés sont exposées dans la AutomationElement.AutomationElementInformation structure.

Les modèles de contrôle ont également des propriétés. Les propriétés des modèles de contrôle sont spécifiques au modèle. Par exemple, ScrollPattern possède des propriétés qui permettent à une application cliente de déterminer si une fenêtre est verticalement ou horizontalement défilante et quelles sont les tailles d’affichage actuelles et les positions de défilement. Les modèles de contrôle exposent toutes leurs propriétés par le biais d’une structure ; par exemple, ScrollPattern.ScrollPatternInformation.

Les propriétés UI Automation sont en lecture seule. Pour définir les propriétés d’un contrôle, vous devez utiliser les méthodes du modèle de contrôle approprié. Par exemple, utilisez Scroll pour modifier les valeurs de position d’une fenêtre de défilement.

Pour améliorer les performances, les valeurs des propriétés des contrôles et des modèles de contrôle peuvent être mises en cache lorsque AutomationElement des objets sont récupérés. Pour plus d’informations, consultez Mise en cache dans les clients UI Automation.

ID de propriété

Les identificateurs de propriété (ID) sont des valeurs constantes uniques qui sont encapsulées dans AutomationProperty des objets. Les applications clientes UI Automation obtiennent ces ID à partir de la classe AutomationElement ou de la classe de modèle de contrôle appropriée, par exemple ScrollPattern. Les fournisseurs UI Automation les obtiennent à partir de AutomationElementIdentifiers ou de l’une des classes d’identificateurs de modèle de contrôle, telles que ScrollPatternIdentifiers.

Le nombre Id d’un AutomationProperty est utilisé par les fournisseurs pour identifier les propriétés pour lesquelles une requête est effectuée dans la méthode IRawElementProviderSimple.GetPropertyValue. En général, les applications clientes n’ont pas besoin d’examiner le Id. Il ProgrammaticName est utilisé uniquement à des fins de débogage et de diagnostic.

Conditions de propriété

Les ID de propriété sont utilisés dans la construction d'objets PropertyCondition utilisés pour rechercher des objets AutomationElement. Par exemple, vous pourriez souhaiter trouver un AutomationElement avec un certain nom ou tous les contrôles activés. Chacun PropertyCondition spécifie un AutomationProperty identificateur et la valeur que la propriété doit correspondre.

Pour plus d’informations, consultez les rubriques de référence suivantes :

Récupération des propriétés

Certaines propriétés de AutomationElement et toutes les propriétés d'une classe de modèle de contrôle sont exposées en tant que propriétés imbriquées de la propriété Current ou Cached de l'objet AutomationElement ou du modèle de contrôle.

En outre, toute AutomationElement propriété de modèle de contrôle, y compris une propriété qui n’est pas disponible dans la structure Cached ou Current, peut être récupérée en utilisant l’une des méthodes suivantes :

Ces méthodes offrent des performances légèrement meilleures, ainsi qu’un accès à la gamme complète de propriétés.

L’exemple de code suivant montre les deux façons de récupérer une propriété sur un 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))

Pour récupérer les propriétés des modèles de contrôle pris en charge par le AutomationElementmodèle de contrôle, vous n’avez pas besoin de récupérer l’objet de modèle de contrôle. Passez simplement l’un des identificateurs de propriété de modèle à la méthode.

L’exemple de code suivant montre les deux façons de récupérer une propriété sur un modèle de contrôle.

// 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))

Les Get méthodes retournent un Object. L’application doit convertir l’objet retourné en type approprié avant d’utiliser la valeur.

Valeurs de propriété par défaut

Si un fournisseur UI Automation n’implémente pas de propriété, le système UI Automation peut fournir une valeur par défaut. Par exemple, si le fournisseur d’un contrôle ne prend pas en charge la propriété identifiée par HelpTextProperty, UI Automation retourne une chaîne vide. De même, si le fournisseur ne prend pas en charge la propriété identifiée par IsDockPatternAvailableProperty, UI Automation retourne false.

Vous pouvez modifier ce comportement à l’aide des surcharges de méthode AutomationElement.GetCachedPropertyValue et AutomationElement.GetCurrentPropertyValue. Lorsque vous spécifiez true comme deuxième paramètre, UI Automation ne retourne pas de valeur par défaut, mais retourne plutôt la valeur NotSupportedspéciale.

L’exemple de code suivant tente de récupérer une propriété à partir d’un élément et, si la propriété n’est pas prise en charge, une valeur définie par l’application est utilisée à la place.

// 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)

Pour découvrir les propriétés prises en charge par un élément, utilisez GetSupportedProperties. Cela retourne un tableau d’identificateurs AutomationProperty .

Événements de changement de propriété

Lorsqu’une valeur de propriété sur un AutomationElement modèle ou un modèle de contrôle change, un événement est déclenché. Une application peut s’abonner à de tels événements en appelant AddAutomationPropertyChangedEventHandler, en fournissant un tableau d’identificateurs AutomationProperty en tant que dernier paramètre afin de spécifier les propriétés d’intérêt.

Dans AutomationPropertyChangedEventHandler, vous pouvez identifier la propriété qui a changé en vérifiant le membre Property des arguments d’événement. Les arguments contiennent également les anciennes et nouvelles valeurs de la propriété UI Automation qui a changé. Ces valeurs sont de type Object et doivent être converties en type correct avant d’être utilisées.

Propriétés AutomationElement supplémentaires

En plus des structures de propriétés Current et Cached, AutomationElement possède les propriétés suivantes, qui sont récupérées par le biais d’accesseurs de propriétés simples.

Propriété	Descriptif
CachedChildren	Collection d’objets AutomationElement enfants qui se trouvent dans le cache.
CachedParent	Objet AutomationElement parent qui se trouve dans le cache.
FocusedElement	(Propriété statique) AutomationElement ayant le focus d’entrée.
RootElement	(Propriété statique) La racine AutomationElement.

Partager via