Automação de Propriedades de Interface de Usuário para Clientes.UI Automation Properties for Clients

Observação

Esta documentação destina-se a desenvolvedores do .NET Framework que querem usar as classes da Automação da interface do usuárioUI Automation gerenciadas definidas no namespace System.Windows.Automation.This documentation is intended for .NET Framework developers who want to use the managed Automação da interface do usuárioUI Automation classes defined in the System.Windows.Automation namespace. Para obter as informações mais recentes sobre a Automação da interface do usuárioUI Automation, consulte Windows Automation API: UI Automation (API de Automação do Windows: Automação da Interface do Usuário).For the latest information about Automação da interface do usuárioUI Automation, see Windows Automation API: UI Automation.

Esta visão geral apresenta a você Automação da interface do usuárioUI Automation Propriedades à medida que elas são expostas aos aplicativos cliente de automação da interface do usuário.This overview introduces you to Automação da interface do usuárioUI Automation properties as they are exposed to UI Automation client applications.

As propriedades em objetos AutomationElement contêm informações sobre elementos UI (interface do usuário)user interface (UI), geralmente controles.Properties on AutomationElement objects contain information about UI (interface do usuário)user interface (UI) elements, usually controls. As propriedades de um AutomationElement são genéricas; ou seja, não é específico para um tipo de controle.The properties of an AutomationElement are generic; that is, not specific to a control type. Muitas dessas propriedades são expostas na estrutura de AutomationElement.AutomationElementInformation.Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.

Os padrões de controle também têm propriedades.Control patterns also have properties. As propriedades dos padrões de controle são específicas do padrão.The properties of control patterns are specific to the pattern. Por exemplo, ScrollPattern tem propriedades que permitem que um aplicativo cliente descubra se uma janela é vertical ou horizontalmente rolável e quais são os tamanhos de exibição e as posições de rolagem atuais.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. Padrões de controle expõem todas as suas propriedades por meio de uma estrutura; por exemplo, ScrollPattern.ScrollPatternInformation.Control patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.

Automação da interface do usuárioUI Automation propriedades são somente leitura.properties are read-only. Para definir as propriedades de um controle, você deve usar os métodos do padrão de controle apropriado.To set properties of a control, you must use the methods of the appropriate control pattern. Por exemplo, use Scroll para alterar os valores de posição de uma janela de rolagem.For example, use Scroll to change the position values of a scrolling window.

Para melhorar o desempenho, os valores de propriedade de controles e padrões de controle podem ser armazenados em cache quando AutomationElement objetos são recuperados.To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. Para obter mais informações, consulte Caching em clientes de automação da interface do usuário.For more information, see Caching in UI Automation Clients.

IDs de propriedadeProperty IDs

Identificadores de propriedade (IDs) são valores exclusivos e constantes que são encapsulados em objetos AutomationProperty.Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. Os aplicativos cliente de automação da interface do usuário obtêm essas IDs da classe AutomationElement ou da classe de padrão de controle apropriada, como ScrollPattern.UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. Os provedores de automação de interface do usuário os obtêm de AutomationElementIdentifiers ou de uma das classes de identificadores de padrão de controle, como ScrollPatternIdentifiers.UI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.

O Id numérico de um AutomationProperty é usado pelos provedores para identificar as propriedades que estão sendo consultadas no método IRawElementProviderSimple.GetPropertyValue.The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. Em geral, os aplicativos cliente não precisam examinar o Id.In general, client applications do not need to examine the Id. O ProgrammaticName é usado somente para fins de depuração e diagnóstico.The ProgrammaticName is used only for debugging and diagnostic purposes.

Condições de propriedadeProperty Conditions

As IDs de propriedade são usadas na construção de objetos PropertyCondition usados para localizar AutomationElement objetos.The property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. Por exemplo, talvez você queira encontrar um AutomationElement que tenha um determinado nome ou todos os controles que estão habilitados.For example, you might wish to find an AutomationElement that has a certain name, or all controls that are enabled. Cada PropertyCondition especifica um identificador de AutomationProperty e o valor que a propriedade deve corresponder.Each PropertyCondition specifies an AutomationProperty identifier and the value that the property must match.

Para obter mais informações, consulte os seguintes tópicos de referência:For more information, see the following reference topics:

Recuperando propriedadesRetrieving Properties

Algumas propriedades de AutomationElement e todas as propriedades de uma classe de padrão de controle são expostas como propriedades aninhadas da propriedade Current ou Cached do objeto de padrão de AutomationElement ou de controle.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.

Além disso, qualquer AutomationElement ou propriedade de padrão de controle, incluindo uma propriedade que não esteja disponível na estrutura Cached ou Current, pode ser recuperada usando um dos seguintes métodos: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:

Esses métodos oferecem um desempenho ligeiramente melhor, bem como o acesso à gama completa de propriedades.These methods offer slightly better performance as well as access to the full range of properties.

O exemplo de código a seguir mostra as duas maneiras de recuperar uma propriedade em um AutomationElement.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))

Para recuperar propriedades de padrões de controle com suporte pelo AutomationElement, não é necessário recuperar o objeto de padrão de controle.To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. Basta passar um dos identificadores de propriedade de padrão para o método.Simply pass one of the pattern property identifiers to the method.

O exemplo de código a seguir mostra as duas maneiras de recuperar uma propriedade em um padrão de controle.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))

Os métodos de Get retornam um Object.The Get methods return an Object. O aplicativo deve converter o objeto retornado para o tipo apropriado antes de usar o valor.The application must cast the returned object to the proper type before using the value.

Valores de propriedade padrãoDefault Property Values

Se um provedor de automação de interface do usuário não implementar uma propriedade, o sistema Automação da interface do usuárioUI Automation será capaz de fornecer um valor padrão.If a UI Automation provider does not implement a property, the Automação da interface do usuárioUI Automation system is able to supply a default value. Por exemplo, se o provedor de um controle não oferecer suporte à propriedade identificada por HelpTextProperty, Automação da interface do usuárioUI Automation retornará uma cadeia de caracteres vazia.For example, if the provider for a control does not support the property identified by HelpTextProperty, Automação da interface do usuárioUI Automation returns an empty string. Da mesma forma, se o provedor não oferecer suporte à propriedade identificada por IsDockPatternAvailableProperty, Automação da interface do usuárioUI Automation retornará false.Similarly, if the provider does not support the property identified by IsDockPatternAvailableProperty, Automação da interface do usuárioUI Automation returns false.

Você pode alterar esse comportamento usando as sobrecargas de método AutomationElement.GetCachedPropertyValue e AutomationElement.GetCurrentPropertyValue.You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. Quando você especifica true como o segundo parâmetro, Automação da interface do usuárioUI Automation não retorna um valor padrão, mas, em vez disso, retorna o valor especial NotSupported.When you specify true as the second parameter, Automação da interface do usuárioUI Automation does not return a default value, but instead returns the special value NotSupported.

O código de exemplo a seguir tenta recuperar uma propriedade de um elemento e, se a propriedade não tiver suporte, um valor definido pelo aplicativo será usado em seu lugar.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)

Para descobrir quais propriedades são suportadas por um elemento, use GetSupportedProperties.To discover what properties are supported by an element, use GetSupportedProperties. Isso retorna uma matriz de identificadores de AutomationProperty.This returns an array of AutomationProperty identifiers.

Eventos de alteração de propriedadeProperty-changed Events

Quando um valor de propriedade em um padrão de AutomationElement ou de controle é alterado, um evento é gerado.When a property value on an AutomationElement or control pattern changes, an event is raised. Um aplicativo pode assinar esses eventos chamando AddAutomationPropertyChangedEventHandler, fornecendo uma matriz de identificadores de AutomationProperty como o último parâmetro para especificar as propriedades de interesse.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.

No AutomationPropertyChangedEventHandler, você pode identificar a propriedade que foi alterada verificando o membro Property dos argumentos do evento.In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. Os argumentos também contêm os valores novos e antigos da propriedade Automação da interface do usuárioUI Automation que foi alterada.The arguments also contain the old and new values of the Automação da interface do usuárioUI Automation property that has changed. Esses valores são do tipo Object e devem ser convertidos para o tipo correto antes de serem usados.These values are of type Object and must be cast to the correct type before being used.

Propriedades de AutomationElement adicionaisAdditional AutomationElement Properties

Além das estruturas de propriedade Current e Cached, AutomationElement tem as seguintes propriedades, que são recuperadas por meio de acessadores de propriedade simples.In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.

PropriedadeProperty DescriçãoDescription
CachedChildren Uma coleção de objetos de AutomationElement filhos que estão no cache.A collection of child AutomationElement objects that are in the cache.
CachedParent Um AutomationElement objeto pai que está no cache.An AutomationElement parent object that is in the cache.
FocusedElement (Propriedade estática) O AutomationElement que tem o foco de entrada.(Static property) The AutomationElement that has the input focus.
RootElement (Propriedade estática) A AutomationElementraiz.(Static property) The root AutomationElement.

Consulte tambémSee also