Automatización del mismo nivel personalizadaCustom automation peers

Describe el concepto de automatización del mismo nivel para la Automatización de la interfaz de usuario de Microsoft y cómo puedes proporcionar compatibilidad de automatización para tu propia clase de interfaz de usuario personalizada.Describes the concept of automation peers for Microsoft UI Automation, and how you can provide automation support for your own custom UI class.

La automatización de la interfaz de usuario proporciona un marco que los clientes de automatización pueden usar para examinar o usar las interfaces de usuario de una variedad de marcos y plataformas de interfaz de usuario.UI Automation provides a framework that automation clients can use to examine or operate the user interfaces of a variety of UI platforms and frameworks. Si está escribiendo una aplicación de Windows, las clases que usa para la interfaz de usuario ya proporcionan compatibilidad con la automatización de la interfaz de usuario.If you are writing a Windows app, the classes that you use for your UI already provide UI Automation support. Puedes derivar de clases no selladas existentes para definir un nuevo tipo de control de la interfaz de usuario o clase de compatibilidad.You can derive from existing, non-sealed classes to define a new kind of UI control or support class. Durante ese proceso, es posible que tu clase incorpore un comportamiento que incluya compatibilidad para accesibilidad pero que la compatibilidad predeterminada para la automatización de la interfaz de usuario no abarca.In the process of doing so, your class might add behavior that should have accessibility support but that the default UI Automation support does not cover. En este caso, debe extender la compatibilidad con la automatización de la interfaz de usuario existente Si deriva de la clase AutomationPeer que usó la implementación base, agrega cualquier compatibilidad necesaria a la implementación del mismo nivel e informa a la infraestructura de control de aplicaciones de Windows que debe crear el nuevo elemento del mismo nivel.In this case, you should extend the existing UI Automation support by deriving from the AutomationPeer class that the base implementation used, adding any necessary support to your peer implementation, and informing the Windows app control infrastructure that it should create your new peer.

La automatización de la interfaz de usuario no solo permite el uso de aplicaciones de accesibilidad y tecnologías de asistencia, como los lectores de pantalla, sino también el código de control de calidad (prueba).UI Automation enables not only accessibility applications and assistive technologies, such as screen readers, but also quality-assurance (test) code. En ambos escenarios, los clientes de automatización de la interfaz de usuario pueden examinar los elementos de la interfaz de usuario y simular la interacción del usuario con tu aplicación desde otro código que no sea el de la aplicación.In either scenario, UI Automation clients can examine user-interface elements and simulate user interaction with your app from other code outside your app. Para obtener información acerca de la automatización de la interfaz de usuario en todas las plataformas y en su sentido más amplio, consulta la introducción a la automatización de la interfaz de usuario.For info about UI Automation across all platforms and in its wider meaning, see UI Automation Overview.

Existen dos públicos diferentes que usan el marco de trabajo de automatización de la interfaz de usuario.There are two distinct audiences who use the UI Automation framework.

  • Los clientes de UI Automation llaman a las API de automatización de la interfaz de usuario para obtener información sobre toda la interfaz de usuario que se muestra actualmente al usuario.UI Automation clients call UI Automation APIs to learn about all of the UI that is currently displayed to the user. Por ejemplo, una tecnología de asistencia como un lector de pantalla actúa como un cliente de automatización de la interfaz de usuario.For example, an assistive technology such as a screen reader acts as a UI Automation client. La interfaz de usuario se presenta como un árbol de elementos de automatización que se relacionan.The UI is presented as a tree of automation elements that are related. El cliente de automatización de la interfaz de usuario probablemente esté interesado solamente en una aplicación por vez o en todo el árbol.The UI Automation client might be interested in just one app at a time, or in the entire tree. El cliente de automatización de la interfaz de usuario puede usar API de automatización de la interfaz de usuario para navegar en el árbol y leer o cambiar información en los elementos de automatización.The UI Automation client can use UI Automation APIs to navigate the tree and to read or change information in the automation elements.
  • Los proveedores de automatización de la interfaz de usuario aportan información al árbol de automatización de la interfaz de usuario mediante la implementación de las API que exponen los elementos de la interfaz de usuario que introdujeron como parte de su aplicación.UI Automation providers contribute information to the UI Automation tree, by implementing APIs that expose the elements in the UI that they introduced as part of their app. Cuando crees un nuevo control, ahora debes actuar como partícipe del escenario de proveedor de automatización de la interfaz de usuario.When you create a new control, you should now act as a participant in the UI Automation provider scenario. Como proveedor, debes asegurarte de que todos los clientes de automatización de la interfaz de usuario puedan usar el marco de trabajo de automatización de la interfaz de usuario para interactuar con tu control, tanto por motivos de accesibilidad como de pruebas.As a provider, you should ensure that all UI Automation clients can use the UI Automation framework to interact with your control for both accessibility and testing purposes.

Generalmente, existen API paralelas en el marco de trabajo de Automatización de la interfaz de usuario: una API para clientes de Automatización de la interfaz de usuario y otra API con nombre similar para los proveedores de Automatización de la interfaz de usuario.Typically there are parallel APIs in the UI Automation framework: one API for UI Automation clients and another, similarly named API for UI Automation providers. La mayor parte de este tema se centra en las API del proveedor de automatización de la interfaz de usuario, concretamente en las clases e interfaces que permiten la extensibilidad del proveedor en ese marco de trabajo de la interfaz de usuario.For the most part, this topic covers the APIs for the UI Automation provider, and specifically the classes and interfaces that enable provider extensibility in that UI framework. En ocasiones, para ofrecer algo de perspectiva, mencionamos las API de automatización de la interfaz de usuario que los clientes de automatización de la interfaz de usuario usan o proporcionamos una tabla de búsqueda que relaciona las API de proveedor y cliente.Occasionally we mention UI Automation APIs that the UI Automation clients use, to provide some perspective, or provide a lookup table that correlates the client and provider APIs. Para obtener más información sobre la perspectiva del cliente, vea la Guía del programador del cliente de UI Automation.For more info about the client perspective, see UI Automation Client Programmer's Guide.

Nota

Normalmente, los clientes de automatización de la interfaz de usuario no usan código administrado y no se implementan como una aplicación para UWP(suelen ser aplicaciones de escritorio).UI Automation clients don't typically use managed code and aren't typically implemented as a UWP app (they are usually desktop apps). La automatización de la interfaz de usuario se basa en un estándar y no en una implementación o marco específicos.UI Automation is based on a standard and not a specific implementation or framework. Muchos clientes de automatización de la interfaz de usuario existentes, incluidos los productos de tecnología de asistencia como los lectores de pantalla, usan interfaces del Modelo de objetos componentes (COM) para interactuar con la automatización de la interfaz de usuario, el sistema y las aplicaciones que se ejecutan en ventanas secundarias.Many existing UI Automation clients, including assistive technology products such as screen readers, use Component Object Model (COM) interfaces to interact with UI Automation, the system, and the apps that run in child windows. Para obtener más información sobre las interfaces COM y cómo escribir un cliente de automatización de la interfaz de usuario mediante COM, consulta los Conceptos básicos sobre la automatización de la interfaz de usuario.For more info on the COM interfaces and how to write a UI Automation client using COM, see UI Automation Fundamentals.

Determinar el estado actual de la compatibilidad para automatización de la interfaz de usuario para tu clase de interfaz de usuario personalizadaDetermining the existing state of UI Automation support for your custom UI class

Antes de intentar implementar un sistema de automatización del mismo nivel para un control personalizado, debes probar si la clase base y su sistema de automatización del mismo nivel proporcionan la compatibilidad para accesibilidad o automatización que necesitas.Before you attempt to implement an automation peer for a custom control, you should test whether the base class and its automation peer already provides the accessibility or automation support that you need. En muchos casos, la combinación de las implementaciones FrameworkElementAutomationPeer, los pares específicos y los modelos que implementan pueden proporcionar una experiencia de accesibilidad básica y, a la vez, satisfactoria.In many cases, the combination of the FrameworkElementAutomationPeer implementations, specific peers, and the patterns they implement can provide a basic but satisfactory accessibility experience. Que esto sea cierto depende de la cantidad de cambios que hayas implementado en la exposición del modelo de objetos al control en comparación con su clase base.Whether this is true depends on how many changes you made to the object model exposure to your control versus its base class. Además, esto depende de si las incorporaciones a la funcionalidad de la clase base se corresponden con los nuevos elementos de la interfaz de usuario en el contrato de la plantilla o con la apariencia visual del control.Also, this depends on whether your additions to base class functionality correlate to new UI elements in the template contract or to the visual appearance of the control. En algunos casos, tus cambios puede incorporar nuevos aspectos de la experiencia del usuario que requieren una compatibilidad para accesibilidad adicional.In some cases your changes might introduce new aspects of user experience that require additional accessibility support.

Incluso si al usar la clase base del mismo nivel se proporciona compatibilidad para accesibilidad básica, sigue considerándose una práctica recomendada definir un sistema del mismo nivel para que puedas proporcionar información precisa sobre ClassName a Automatización de la interfaz de usuario para escenarios de prueba automatizada.Even if using the existing base peer class provides the basic accessibility support, it is still a best practice to define a peer so that you can report precise ClassName information to UI Automation for automated testing scenarios. Esta consideración es especialmente importante si estás escribiendo un control que está destinado a su consumo por parte de terceros.This consideration is especially important if you are writing a control that is intended for third-party consumption.

Clases de automatización del mismo nivelAutomation peer classes

UWP se basa en convenciones y técnicas de automatización de la interfaz de usuario existentes usadas por marcos de interfaz de usuario de código administrado anteriores, como Windows Forms, Windows Presentation Foundation (WPF) y Microsoft Silverlight.The UWP builds on existing UI Automation techniques and conventions used by previous managed-code UI frameworks such as Windows Forms, Windows Presentation Foundation (WPF) and Microsoft Silverlight. Muchas de las clases de control, y su función y propósito, también derivan de un marco de trabajo de la interfaz de usuario anterior.Many of the control classes and their function and purpose also have their origin in a previous UI framework.

Por convención, los nombres de clase del mismo nivel empiezan por el nombre de clase del control y terminan por "AutomationPeer".By convention, peer class names begin with the control class name and end with "AutomationPeer". Por ejemplo, ButtonAutomationPeer es la clase del mismo nivel para la clase de control Button.For example, ButtonAutomationPeer is the peer class for the Button control class.

Nota

Para los fines de este tema, tratamos las propiedades que se relacionan con la accesibilidad como si fueran más importantes al implementar un sistema del mismo nivel de control.For purposes of this topic, we treat the properties that are related to accessibility as being more important when you implement a control peer. Pero para lograr un concepto más general de la compatibilidad con la Automatización de la interfaz de usuario, debes implementar un sistema del mismo nivel de acuerdo con las recomendaciones documentadas en la guía del programador de proveedores de Automatización de la interfaz de usuario y en los conceptos básicos de la Automatización de la interfaz de usuario.But for a more general concept of UI Automation support, you should implement a peer in accordance with recommendations as documented by the UI Automation Provider Programmer's Guide and UI Automation Fundamentals. Esos temas no abarcan las API AutomationPeer específicas que deberías usar para proporcionar la información de marco de UWP para Automatización de la interfaz de usuario, pero describen las propiedades que identifican tu clase o proporcionan otra información o interacción.Those topics don't cover the specific AutomationPeer APIs that you would use to provide the information in the UWP framework for UI Automation, but they do describe the properties that identify your class or provide other information or interaction.

Sistemas del mismo nivel, patrones y tipos de controlPeers, patterns and control types

Un patrón de control es una implementación de la interfaz que expone un aspecto específico de una funcionalidad de un control a un cliente de automatización de la interfaz de usuario.A control pattern is an interface implementation that exposes a particular aspect of a control's functionality to a UI Automation client. Los clientes de automatización de la interfaz de usuario usan las propiedades y los métodos expuestos a través de un patrón de control para recuperar información sobre las funcionalidades del control o manipular el comportamiento en tiempo de ejecución del control.UI Automation clients use the properties and methods exposed through a control pattern to retrieve information about capabilities of the control, or to manipulate the control's behavior at run time.

Los patrones de control proporcionan una manera de categorizar y exponer la funcionalidad de un control independientemente de su tipo o apariencia.Control patterns provide a way to categorize and expose a control's functionality independent of the control type or the appearance of the control. Por ejemplo, un control que presenta una interfaz tabular usa el patrón de control Grid para exponer el número de filas y columnas en la tabla, y para permitir que un cliente de Automatización de la interfaz de usuario pueda recuperar elementos de la tabla.For example, a control that presents a tabular interface uses the Grid control pattern to expose the number of rows and columns in the table, and to enable a UI Automation client to retrieve items from the table. Como en otros ejemplos, el cliente de Automatización de la interfaz de usuario puede usar el patrón de control Invoke para los controles que pueden invocarse (como botones), y el patrón de control Scroll para los controles que tienen barras de desplazamiento, (como cuadros de lista, vistas de lista o cuadros combinados).As other examples, the UI Automation client can use the Invoke control pattern for controls that can be invoked, such as buttons, and the Scroll control pattern for controls that have scroll bars, such as list boxes, list views, or combo boxes. Cada patrón de control representa un tipo de funcionalidad independiente y es posible combinar los patrones de control para describir el conjunto completo de funcionalidades admitidas por un control en particular.Each control pattern represents a separate type of functionality, and control patterns can be combined to describe the full set of functionality supported by a particular control.

Los patrones de control se relacionan con la interfaz de usuario del mismo modo en que las interfaces se relacionan con los objetos COM.Control patterns relate to UI as interfaces relate to COM objects. En COM, puedes consultar a un objeto para preguntar qué interfaces admite y después usar esas interfaces para acceder a la funcionalidad.In COM, you can query an object to ask what interfaces it supports and then use those interfaces to access functionality. En la automatización de la interfaz de usuario, los clientes pueden preguntar a un elemento de automatización de la interfaz de usuario qué patrones de control admite y, después, interactuar con el elemento y su control del mismo nivel a través de las propiedades, los métodos, los eventos y las estructuras expuestos por los patrones de control admitidos.In UI Automation, UI Automation clients can query a UI Automation element to find out which control patterns it supports, and then interact with the element and its peered control through the properties, methods, events, and structures exposed by the supported control patterns.

Uno de los principales objetivos de un sistema de automatización del mismo nivel es notificar a un cliente de automatización de la interfaz de usuario de cuáles son los patrones de control compatibles con el elemento de la interfaz de usuario mediante el sistema del mismo nivel.One of the main purposes of an automation peer is to report to a UI Automation client which control patterns the UI element can support through its peer. Para hacerlo, los proveedores de Automatización de la interfaz de usuario implementan nuevos sistemas del mismo nivel que cambian el comportamiento del método GetPattern mediante la anulación del método GetPatternCore.To do this, UI Automation providers implement new peers that change the GetPattern method behavior by overriding the GetPatternCore method. Los clientes de Automatización de la interfaz de usuario realizan llamadas que el proveedor de Automatización de la interfaz de usuario asigna al GetPattern que realiza la llamada.UI Automation clients make calls that the UI Automation provider maps to calling GetPattern . Los clientes de Automatización de la interfaz de usuario consultan cada patrón específico con el que quieren interactuar.UI Automation clients query for each specific pattern that they want to interact with. Si el elemento del mismo nivel admite el patrón, se devuelve a sí mismo una referencia a un objeto; de lo contrario, devuelve null .If the peer supports the pattern, it returns an object reference to itself; otherwise it returns null . Si no se devuelve null , el cliente de Automatización de la interfaz de usuario espera poder llamar a las API de la interfaz del patrón como un cliente, con el fin de interactuar con ese patrón de control.If the return is not null , the UI Automation client expects that it can call APIs of the pattern interface as a client, in order to interact with that control pattern.

Un tipo de control es una manera de definir ampliamente la funcionalidad de un control representado por el sistema del mismo nivel.A control type is a way to broadly define the functionality of a control that the peer represents. Este es un concepto distinto al del patrón de control, porque mientras que un patrón informa a la Automatización de la interfaz de usuario de la información que puede obtener o de las acciones que puede realizar a través de una interfaz en particular, el tipo de control se encuentra en un nivel superior.This is a different concept than a control pattern because while a pattern informs UI Automation what info it can get or what actions it can perform through a particular interface, the control type exists one level above that. Cada tipo de control incluye orientación sobre estos aspectos de la automatización de la interfaz de usuario:Each control type has guidance about these aspects of UI Automation:

  • Patrones de control de automatización de la interfaz de usuario: un tipo de control podría admitir más de un patrón, cada uno de los cuales representa una clasificación distinta de información o interacción.UI Automation control patterns: A control type might support more than one pattern, each of which represents a different classification of info or interaction. Cada tipo de control tiene un conjunto de patrones de control que el control debe admitir, un conjunto que es opcional, y otro conjunto que el control no debe admitir.Each control type has a set of control patterns that the control must support, a set that is optional, and a set that the control must not support.
  • Valores de propiedad de la automatización de la interfaz de usuario: cada tipo de control tiene un conjunto de propiedades que el control debe admitir.UI Automation property values: Each control type has a set of properties that the control must support. Se trata de propiedades generales, como se describe en Introducción a las propiedades de automatización de la interfaz de usuario, no de propiedades que sean específicas del patrón.These are the general properties, as described in UI Automation Properties Overview, not the ones that are pattern-specific.
  • Eventos de automatización de la interfaz de usuario: cada tipo de control tiene un conjunto de eventos que el control debe admitir.UI Automation events: Each control type has a set of events that the control must support. De nuevo, son generales, no específicas del patrón, como se describe en información general sobre eventos de automatizaciónde la interfaz de usuario.Again these are general, not pattern-specific, as described in UI Automation Events Overview.
  • Estructura de árbol de automatización de la interfaz de usuario: cada tipo de control define el modo en que debe aparecer el control en la estructura de árbol de automatización de la interfaz de usuario.UI Automation tree structure: Each control type defines how the control must appear in the UI Automation tree structure.

Independientemente de cómo se implementen los sistemas del mismo nivel de automatización para el marco, el cliente de Automatización de la interfaz de usuario no está ligada a UWP; de hecho, es probable que los clientes de Automatización de la interfaz de usuario, como las tecnologías de asistencia, usen otros modelos de programación tales como COM.Regardless of how automation peers for the framework are implemented, UI Automation client functionality isn't tied to the UWP, and in fact it's likely that existing UI Automation clients such as assistive technologies will use other programming models, such as COM. En COM, los clientes pueden usar QueryInterface para la interfaz del patrón de control de COM que implementa el patrón solicitado o el marco general de Automatización de la interfaz de usuario para las propiedades, los eventos o el examen del árbol.In COM, clients can QueryInterface for the COM control pattern interface that implements the requested pattern or the general UI Automation framework for properties, events or tree examination. En el caso de los patrones, el marco de trabajo de automatización de la interfaz de usuario calcula la referencia de ese código de interfaz en todo el código de UWP en el proveedor de automatización de la interfaz de usuario y el sistema del mismo nivel pertinente.For the patterns, the UI Automation framework marshals that interface code across into UWP code running against the app's UI Automation provider and the relevant peer.

Cuando se implementan patrones de control para un marco de código administrado, como una aplicación de UWP con C # o Microsoft Visual Basic, se pueden usar .NET Framework interfaces para representar estos patrones en lugar de usar la representación de la interfaz com.When you implement control patterns for a managed-code framework such as a UWP app using C# or Microsoft Visual Basic, you can use .NET Framework interfaces to represent these patterns instead of using the COM interface representation. Por ejemplo, la interfaz de patrón de automatización de la interfaz de usuario para una implementación de proveedor Microsoft .NET del patrón Invoke es IInvokeProvider.For example, the UI Automation pattern interface for a Microsoft .NET provider implementation of the Invoke pattern is IInvokeProvider.

Para obtener una lista de los patrones de control, interfaces de proveedor y sus finalidades, consulta el tema sobre interfaces y patrones de control.For a list of control patterns, provider interfaces, and their purpose, see Control patterns and interfaces. Para obtener la lista de los tipos de control, vea UI Automation Control Types Overview.For the list of the control types, see UI Automation Control Types Overview.

Instrucciones para implementar patrones de controlGuidance for how to implement control patterns

Los patrones de control y su finalidad son parte de una definición más grande del marco de automatización de la interfaz de usuario y no solo se aplican a la compatibilidad con accesibilidad para una aplicación para UWP.The control patterns and what they're intended for are part of a larger definition of the UI Automation framework, and don't just apply to the accessibility support for a UWP app. Cuando implemente un patrón de control, debe asegurarse de que lo está implementando de forma que coincida con las instrucciones que se documentan en estos documentos y también en la especificación de automatización de la interfaz de usuario.When you implement a control pattern you should make sure you're implementing it in a way that matches the guidance as documented in these docs and also in the UI Automation specification. Si busca instrucciones, en general puede usar la documentación de Microsoft y no necesitará hacer referencia a la especificación.If you're looking for guidance, you can generally use the Microsoft documentation and won't need to refer to the specification. Las instrucciones para cada patrón se detallan en el tema sobre la implementación de patrones de control de automatización de la interfaz de usuario.Guidance for each pattern is documented here: Implementing UI Automation Control Patterns. Verás que cada tema bajo esta área tiene una sección sobre convenciones e instrucciones de implementación y otra sección sobre los miembros necesarios.You'll notice that each topic under this area has an "Implementation Guidelines and Conventions" section and "Required Members" section. Las instrucciones suelen hacer referencia a determinadas API de la interfaz del patrón de control relevante en la referencia sobre interfaces de patrones de control para proveedores.The guidance usually refers to specific APIs of the relevant control pattern interface in the Control Pattern Interfaces for Providers reference. Estas interfaces son interfaces nativas o de COM (y sus API usan la sintaxis de estilo COM).Those interfaces are the native/COM interfaces (and their APIs use COM-style syntax). Pero todo lo que ves allí tiene un equivalente en el espacio de nombres Windows.UI.Xaml.Automation.Provider.But everything you see there has an equivalent in the Windows.UI.Xaml.Automation.Provider namespace.

Si estás usando los sistemas del mismo nivel de automatización predeterminados y ampliando su comportamiento, ten en cuenta que estos sistemas del mismo nivel ya han sido escritos de acuerdo con las directrices de Automatización de la interfaz de usuario.If you're using the default automation peers and expanding on their behavior, those peers have already been written in conformance to UI Automation guidelines. Si admiten patrones de control, puedes confiar en la compatibilidad de ese patrón de acuerdo con las instrucciones del tema sobre la implementación de patrones de control de automatización de la interfaz de usuario.If they support control patterns, you can rely on that pattern support conforming with guidance at Implementing UI Automation Control Patterns. Si un sistema de control del mismo nivel notifica que es representativo de un tipo de control definido por la automatización de la interfaz de usuario, quiere decir que ha seguido las instrucciones documentadas en el tema sobre compatibilidad con tipos de control de automatización de la interfaz de usuario.If a control peer reports that it's representative of a control type defined by UI Automation, then the guidance documented at Supporting UI Automation Control Types has been followed by that peer.

Sin embargo, es posible que necesites más instrucciones para que los patrones de control o los tipos de control puedan seguir las recomendaciones de automatización de la interfaz de usuario en tu implementación del mismo nivel.Nevertheless you might need additional guidance for control patterns or control types in order to follow the UI Automation recommendations in your peer implementation. Esto suele suceder particularmente cuando estás implementando compatibilidad con patrones o tipos de control que aún no existe como implementación predeterminada en un control de UWP.That would be particularly true if you're implementing pattern or control type support that doesn't yet exist as a default implementation in a UWP control. Por ejemplo, el patrón para anotaciones no se implementa en ninguno de los controles XAML predeterminados.For example, the pattern for annotations isn't implemented in any of the default XAML controls. Pero puede que tengas una aplicación que usa anotaciones de manera extensa y, por tanto, quieras subir a la superficie esa funcionalidad para que esté accesible.But you might have an app that uses annotations extensively and therefore you want to surface that functionality to be accessible. Para este escenario, el sistema del mismo nivel debe implementar IAnnotationProvider y probablemente debería identificarse como tipo de control Document con propiedades adecuadas para indicar que los documentos admiten la anotación.For this scenario, your peer should implement IAnnotationProvider and should probably report itself as the Document control type with appropriate properties to indicate that your documents support annotation.

Se recomienda seguir las instrucciones para los patrones de la sección sobre implementación de patrones de control de automatización del mismo nivel o los tipos de control en el tema sobre compatibilidad con tipos de control de Automatización de la interfaz de usuario como orientación e instrucciones generales.We recommend that you use the guidance that you see for the patterns under Implementing UI Automation Control Patterns or control types under Supporting UI Automation Control Types as orientation and general guidance. Puedes incluso intentar seguir algunos de los vínculos de las API para obtener descripciones y notas con referencia a las API.You might even try following some of the API links for descriptions and remarks as to the purpose of the APIs. Pero para la información específica sobre la sintaxis necesaria para la programación de aplicaciones para UWP, busca la API equivalente dentro del espacio de nombres Windows.UI.Xaml.Automation.Provider y usa esas páginas de referencia para obtener más información.But for syntax specifics that are needed for UWP app programming, find the equivalent API within the Windows.UI.Xaml.Automation.Provider namespace and use those reference pages for more info.

Clases integradas de sistemas de automatización del mismo nivelBuilt-in automation peer classes

En general, los elementos implementan una clase de sistemas de automatización del mismo nivel si aceptan actividad de interfaz de usuario por parte de este o si contienen información que necesitan los usuarios de tecnologías de asistencia que representan la interfaz de usuario interactiva o significativa de las aplicaciones.In general, elements implement an automation peer class if they accept UI activity from the user, or if they contain information needed by users of assistive technologies that represent the interactive or meaningful UI of apps. No todos los elementos visuales de UWP tienen sistemas de automatización del mismo nivel.Not all UWP visual elements have automation peers. Algunos ejemplos de las clases que implementan sistemas de automatización del mismo nivel son Button y TextBox.Examples of classes that implement automation peers are Button and TextBox. Algunos ejemplos de clases que no implementan sistemas de automatización del mismo nivel son Border y las clases basadas en Panel, como Grid y Canvas.Examples of classes that do not implement automation peers are Border and classes based on Panel, such as Grid and Canvas. Un Panel no tiene un sistema del mismo nivel porque proporciona un comportamiento de diseño que es únicamente visual.A Panel has no peer because it is providing a layout behavior that is visual only. No hay ninguna manera accesible de que el usuario interactúe con un Panel .There is no accessibility-relevant way for the user to interact with a Panel . En su lugar, todos los elementos secundarios que contenga un Panel se notifican a los árboles de Automatización de la interfaz de usuario como elementos secundarios del siguiente elemento primario del árbol que tenga una representación de elemento o de sistema del mismo nivel.Whatever child elements a Panel contains are instead reported to UI Automation trees as child elements of the next available parent in the tree that has a peer or element representation.

Límites del proceso de UWP y automatización de la interfaz de usuarioUI Automation and UWP process boundaries

Por lo general, el código de cliente de automatización de la interfaz de usuario que tiene acceso a una aplicación para UWP se ejecuta fuera de proceso.Typically, UI Automation client code that accesses a UWP app runs out-of-process. La infraestructura de marco de trabajo de automatización de la interfaz de usuario permite que la información atraviese los límites del proceso.The UI Automation framework infrastructure enables information to get across the process boundary. Este concepto se explica con más detalle en aspectos básicosde la automatización de la interfaz de usuario.This concept is explained in more detail in UI Automation Fundamentals.

OnCreateAutomationPeerOnCreateAutomationPeer

Todas las clases que derivan del objeto UIElement contienen el método virtual protegido OnCreateAutomationPeer.All classes that derive from UIElement contain the protected virtual method OnCreateAutomationPeer. La secuencia de inicialización de objetos para los sistemas de automatización del mismo nivel llama a OnCreateAutomationPeer para obtener el objeto de automatización del mismo nivel para cada control y así construir un árbol de Automatización de la interfaz de usuario para uso de tiempo de ejecución.The object initialization sequence for automation peers calls OnCreateAutomationPeer to get the automation peer object for each control and thus to construct a UI Automation tree for run-time use. El código de Automatización de la interfaz de usuario puede usar el sistema del mismo nivel para obtener información sobre las características de un control y para simular el uso interactivo por medio de sus patrones de control.UI Automation code can use the peer to get information about a control’s characteristics and features and to simulate interactive use by means of its control patterns. Un control personalizado que admite automatización debe invalidar OnCreateAutomationPeer y devolver una instancia de una clase que deriva de AutomationPeer.A custom control that supports automation must override OnCreateAutomationPeer and return an instance of a class that derives from AutomationPeer. Por ejemplo, si un control personalizado se deriva de la clase ButtonBase , el objeto devuelto por OnCreateAutomationPeer debe derivar de ButtonBaseAutomationPeer.For example, if a custom control derives from the ButtonBase class, the object returned by OnCreateAutomationPeer should derive from ButtonBaseAutomationPeer.

Si estás escribiendo una clase de control personalizada y pretendes suministrar también un nuevo sistema del mismo nivel de automatización, debes invalidar el método OnCreateAutomationPeer de tu control personalizado para que devuelva una nueva instancia del sistema del mismo nivel.If you're writing a custom control class and intend to also supply a new automation peer, you should override the OnCreateAutomationPeer method for your custom control so that it returns a new instance of your peer. La clase del mismo nivel debe derivar directa o indirectamente de AutomationPeer.Your peer class must derive directly or indirectly from AutomationPeer.

Por ejemplo, el siguiente código declara que el control personalizado NumericUpDown debe usar NumericUpDownPeer del mismo nivel para fines de Automatización de la interfaz de usuario.For example, the following code declares that the custom control NumericUpDown should use the peer NumericUpDownPeer for UI Automation purposes.

using Windows.UI.Xaml.Automation.Peers;
...
public class NumericUpDown : RangeBase {
    public NumericUpDown() {
    // other initialization; DefaultStyleKey etc.
    }
    ...
    protected override AutomationPeer OnCreateAutomationPeer()
    {
        return new NumericUpDownAutomationPeer(this);
    }
}
Public Class NumericUpDown
    Inherits RangeBase
    ' other initialization; DefaultStyleKey etc.
       Public Sub New()
       End Sub
       Protected Overrides Function OnCreateAutomationPeer() As AutomationPeer
              Return New NumericUpDownAutomationPeer(Me)
       End Function
End Class
// NumericUpDown.idl
namespace MyNamespace
{
    runtimeclass NumericUpDown : Windows.UI.Xaml.Controls.Primitives.RangeBase
    {
        NumericUpDown();
        Int32 MyProperty;
    }
}

// NumericUpDown.h
...
struct NumericUpDown : NumericUpDownT<NumericUpDown>
{
    ...
    Windows::UI::Xaml::Automation::Peers::AutomationPeer OnCreateAutomationPeer()
    {
        return winrt::make<MyNamespace::implementation::NumericUpDownAutomationPeer>(*this);
    }
};
//.h
public ref class NumericUpDown sealed : Windows::UI::Xaml::Controls::Primitives::RangeBase
{
// other initialization not shown
protected:
    virtual AutomationPeer^ OnCreateAutomationPeer() override
    {
         return ref new NumericUpDownAutomationPeer(this);
    }
};

Nota

La implementación de OnCreateAutomationPeer no debe hacer nada más que inicializar una nueva instancia de la automatización del mismo nivel personalizada, pasando el control de llamada como propietario, y devolver esa instancia.The OnCreateAutomationPeer implementation should do nothing more than initialize a new instance of your custom automation peer, passing the calling control as owner, and return that instance. No intentes ninguna lógica adicional en este método.Do not attempt additional logic in this method. En particular, cualquier lógica que pudiera provocar la destrucción del AutomationPeer en la misma llamada podría provocar un comportamiento inesperado del tiempo de ejecución.In particular, any logic that could potentially lead to destruction of the AutomationPeer within the same call may result in unexpected runtime behavior.

En las implementaciones típicas de OnCreateAutomationPeer, se especifica el propietario como this o Me porque la invalidación del método está en el mismo ámbito que el resto de la definición de clase de control.In typical implementations of OnCreateAutomationPeer, the owner is specified as this or Me because the method override is in the same scope as the rest of the control class definition.

La definición de clase del mismo nivel se puede hacer en el mismo archivo de código o en un archivo de código independiente.The actual peer class definition can be done in the same code file as the control or in a separate code file. Todas las definiciones de sistemas del mismo nivel existen en el espacio de nombres Windows.UI.Xaml.Automation.Peers independiente de los controles para los que proporcionan sistemas del mismo nivel.The peer definitions all exist in the Windows.UI.Xaml.Automation.Peers namespace that is a separate namespace from the controls that they provide peers for. También puedes optar por declarar los sistemas del mismo nivel en espacios de nombres diferentes, siempre que hagas referencia a los espacios de nombres necesarios para la llamada al método OnCreateAutomationPeer.You can choose to declare your peers in separate namespaces also, as long as you reference the necessary namespaces for the OnCreateAutomationPeer method call.

Elección de la clase base del mismo nivel correctaChoosing the correct peer base class

Asegúrate de que tu AutomationPeer derive de una clase base que sea la mejor opción para la lógica de sistema del mismo nivel existente de la clase de control de la que derivas.Make sure that your AutomationPeer is derived from a base class that gives you the best match for the existing peer logic of the control class you are deriving from. En el caso del ejemplo anterior, dado que NumericUpDown deriva de RangeBase, existe una clase RangeBaseAutomationPeer disponible en la que debes basar tu sistema del mismo nivel.In the case of the previous example, because NumericUpDown derives from RangeBase, there is a RangeBaseAutomationPeer class available that you should base your peer on. Mediante el uso de la clase del mismo nivel coincidente más cercana en paralelo con el modo en que derivas el control en sí, puedes evitar invalidar al menos parte de la funcionalidad de IRangeValueProvider porque la clase base del mismo nivel ya la implementa.By using the closest matching peer class in parallel to how you derive the control itself, you can avoid overriding at least some of the IRangeValueProvider functionality because the base peer class already implements it.

La clase Control base no tiene una clase correspondiente del mismo nivel.The base Control class does not have a corresponding peer class. Si necesitas una clase del mismo nivel para que se corresponda con un control personalizado que deriva de Control , deriva la clase del mismo nivel personalizada de FrameworkElementAutomationPeer.If you need a peer class to correspond to a custom control that derives from Control , derive the custom peer class from FrameworkElementAutomationPeer.

Si derivas directamente de ContentControl, esa clase no tiene comportamiento de automatización del mismo nivel predeterminado porque no existe ninguna implementación OnCreateAutomationPeer que haga referencia a una clase del mismo nivel.If you derive from ContentControl directly, that class has no default automation peer behavior because there is no OnCreateAutomationPeer implementation that references a peer class. Por lo tanto, asegúrate de implementar OnCreateAutomationPeer para usar tu propio sistema del mismo nivel, o usa FrameworkElementAutomationPeer como el sistema del mismo nivel si ese nivel de compatibilidad de accesibilidad es suficiente para tu control.So make sure either to implement OnCreateAutomationPeer to use your own peer, or to use FrameworkElementAutomationPeer as the peer if that level of accessibility support is adequate for your control.

Nota

Normalmente no derivas de AutomationPeer en lugar de FrameworkElementAutomationPeer.You don't typically derive from AutomationPeer rather than FrameworkElementAutomationPeer. Si ha derivado directamente de AutomationPeer , deberá duplicar una gran cantidad de compatibilidad básica de accesibilidad que, de otro modo, proviene de FrameworkElementAutomationPeer .If you did derive directly from AutomationPeer you'll need to duplicate a lot of basic accessibility support that would otherwise come from FrameworkElementAutomationPeer .

Inicialización de una clase del mismo nivel personalizadaInitialization of a custom peer class

El sistema de automatización del mismo nivel debe definir un constructor con seguridad de tipos que use una instancia del control propietario para la inicialización base.The automation peer should define a type-safe constructor that uses an instance of the owner control for base initialization. En el ejemplo siguiente, la implementación pasa el valor Owner a la base RangeBaseAutomationPeer y, en última instancia, es el FrameworkElementAutomationPeer que usa realmente Owner para establecer FrameworkElementAutomationPeer. Owner.In the next example, the implementation passes the owner value on to the RangeBaseAutomationPeer base, and ultimately it is the FrameworkElementAutomationPeer that actually uses owner to set FrameworkElementAutomationPeer.Owner.

public NumericUpDownAutomationPeer(NumericUpDown owner): base(owner)
{}
Public Sub New(owner As NumericUpDown)
    MyBase.New(owner)
End Sub
// NumericUpDownAutomationPeer.idl
import "NumericUpDown.idl";
namespace MyNamespace
{
    runtimeclass NumericUpDownAutomationPeer : Windows.UI.Xaml.Automation.Peers.AutomationPeer
    {
        NumericUpDownAutomationPeer(NumericUpDown owner);
        Int32 MyProperty;
    }
}

// NumericUpDownAutomationPeer.h
...
struct NumericUpDownAutomationPeer : NumericUpDownAutomationPeerT<NumericUpDownAutomationPeer>
{
    ...
    NumericUpDownAutomationPeer(MyNamespace::NumericUpDown const& owner);
};
//.h
public ref class NumericUpDownAutomationPeer sealed :  Windows::UI::Xaml::Automation::Peers::RangeBaseAutomationPeer
//.cpp
public:    NumericUpDownAutomationPeer(NumericUpDown^ owner);

Métodos Core de AutomationPeerCore methods of AutomationPeer

Por cuestiones de infraestructura de UWP, los métodos que se pueden invalidar de un sistema de automatización del mismo nivel forman parte de un par de métodos: el método de acceso público que el proveedor de Automatización de la interfaz de usuario usa como punto de reenvío para los clientes de Automatización de la interfaz de usuario y el método de personalización "Core" protegido que una clase de UWP puede invalidar para influir en el comportamiento.For UWP infrastructure reasons, the overridable methods of an automation peer are part of a pair of methods: the public access method that the UI Automation provider uses as a forwarding point for UI Automation clients, and the protected "Core" customization method that a UWP class can override to influence the behavior. Estos dos métodos se conectan entre sí de manera predeterminada de tal manera que la llamada al método de acceso siempre invoca el método "Core" paralelo que tiene la implementación del proveedor o, como reserva, invoca una implementación predeterminada de las clases base.The method pair is wired together by default in such a way that the call to the access method always invokes the parallel "Core" method that has the provider implementation, or as a fallback, invokes a default implementation from the base classes.

Cuando se implemente un sistema del mismo nivel para un control personalizado, invalida cualquiera de los métodos "Core" desde la clase base de sistemas de automatización del mismo nivel donde quieres exponer comportamiento exclusivo para tu control personalizado.When implementing a peer for a custom control, override any of the "Core" methods from the base automation peer class where you want to expose behavior that is unique to your custom control. Para obtener información sobre tu control, el código de automatización de la interfaz de usuario llama a los métodos públicos de la clase del mismo nivel.UI Automation code gets information about your control by calling public methods of the peer class. Para proporcionar información acerca de tu control, invalida cada método con un nombre que termine con "Core" cuando el diseño y la implementación de tu control cree escenarios de accesibilidad u otros escenarios de Automatización de la interfaz de usuario que difieran de lo que admite la clase base de sistemas de automatización del mismo nivel.To provide information about your control, override each method with a name that ends with "Core" when your control implementation and design creates accessibility scenarios or other UI Automation scenarios that differ from what's supported by the base automation peer class.

Como mínimo, siempre que definas una nueva clase del mismo nivel, implementa el método GetClassNameCore, como se muestra en el ejemplo siguiente.At a minimum, whenever you define a new peer class, implement the GetClassNameCore method, as shown in the next example.

protected override string GetClassNameCore()
{
    return "NumericUpDown";
}

Nota

Quizás quieras almacenar las cadenas como constantes en lugar de directamente en el cuerpo del método, pero eso depende de ti.You might want to store the strings as constants rather than directly in the method body, but that is up to you. En el caso de GetClassNameCore, no necesitarás localizar esta cadena.For GetClassNameCore, you won't need to localize this string. La propiedad LocalizedControlType se usa cada vez que un cliente de automatización de la interfaz de usuario necesita una cadena localizada, no className .The LocalizedControlType property is used any time a localized string is needed by a UI Automation client, not ClassName .

GetAutomationControlType GetAutomationControlType

Algunas tecnologías de asistencia usan el valor GetAutomationControlType directamente cuando notifican características de los elementos en un árbol de Automatización de la interfaz de usuario, como información adicional del valor Name de Automatización de la interfaz de usuario.Some assistive technologies use the GetAutomationControlType value directly when reporting characteristics of the items in a UI Automation tree, as additional information beyond the UI Automation Name . Si tu control es muy diferente del control del que derivas y quieres notificar un tipo de control diferente del notificado por la clase base del mismo nivel que usa el control, debes implementar un sistema del mismo nivel e invalidar GetAutomationControlTypeCore en tu implementación del mismo nivel.If your control is significantly different from the control you are deriving from and you want to report a different control type from what is reported by the base peer class used by the control, you must implement a peer and override GetAutomationControlTypeCore in your peer implementation. Esto es particularmente importante si derivas desde una clase base generalizada como ItemsControl o ContentControl, donde el sistema del mismo nivel base no proporciona información precisa acerca del tipo de control.This is particularly important if you derive from a generalized base class such as ItemsControl or ContentControl, where the base peer doesn't provide precise information about control type.

La implementación de GetAutomationControlTypeCore describe el control con el valor AutomationControlType.Your implementation of GetAutomationControlTypeCore describes your control by returning an AutomationControlType value. Si bien puedes devolver AutomationControlType.Custom , deberías devolver uno de los tipos de control más específicos si alguno de ellos describe con mayor precisión los escenarios principales de tu control.Although you can return AutomationControlType.Custom , you should return one of the more specific control types if it accurately describes your control's main scenarios. Aquí tiene un ejemplo.Here's an example.

protected override AutomationControlType GetAutomationControlTypeCore()
{
    return AutomationControlType.Spinner;
}

Nota

A menos que especifiques AutomationControlType.Custom, no tienes que implementar GetLocalizedControlTypeCore para proporcionar una propiedad LocalizedControlType a los clientes.Unless you specify AutomationControlType.Custom, you don't have to implement GetLocalizedControlTypeCore to provide a LocalizedControlType property value to clients. La infraestructura común de UI Automation proporciona cadenas traducidas para cada valor de AutomationControlType posible que no sea AutomationControlType. Custom .UI Automation common infrastructure provides translated strings for every possible AutomationControlType value other than AutomationControlType.Custom .

GetPattern y GetPatternCoreGetPattern and GetPatternCore

Una implementación de GetPatternCore de un sistema del mismo nivel devuelve el objeto que admite el patrón solicitado en el parámetro de entrada.A peer's implementation of GetPatternCore returns the object that supports the pattern that is requested in the input parameter. Específicamente, un cliente de Automatización de la interfaz de usuario llama a un método que se reenvía al método GetPattern del proveedor y especifica un valor de enumeración PatternInterface que asigna nombre al patrón solicitado.Specifically, a UI Automation client calls a method that is forwarded to the provider's GetPattern method, and specifies a PatternInterface enumeration value that names the requested pattern. La invalidación de GetPatternCore debería devolver el objeto que implementa el modelo especificado.Your override of GetPatternCore should return the object that implements the specified pattern. Ese objeto es el propio sistema del mismo nivel, porque el sistema del mismo nivel debe implementar la interfaz de patrón correspondiente siempre que notifica que admite un patrón.That object is the peer itself, because the peer should implement the corresponding pattern interface any time that it reports that it supports a pattern. Si tu sistema del mismo nivel no tiene una implementación personalizada de un patrón, pero sabes que la base de este implementa el patrón, puedes llamar a la implementación de GetPatternCore del tipo base desde tu GetPatternCore .If your peer does not have a custom implementation of a pattern, but you know that the peer's base does implement the pattern, you can call the base type's implementation of GetPatternCore from your GetPatternCore . Un GetPatternCore de un sistema del mismo nivel devolverá null si este no admite un patrón.A peer's GetPatternCore should return null if a pattern is not supported by the peer. Sin embargo, en lugar de devolver null directamente desde tu implementación, normalmente usarás la llamada a la implementación base para devolver null para cualquier patrón no admitido.However, instead of returning null directly from your implementation, you would usually rely on the call to the base implementation to return null for any unsupported pattern.

Cuando se admite un patrón, la implementación de GetPatternCore implementación puede devolver this o Me .When a pattern is supported, the GetPatternCore implementation can return this or Me . La expectativa es que el cliente de automatización de la interfaz de usuario convierta el valor devuelto de GetPattern a la interfaz de patrón solicitada siempre que no sea null .The expectation is that the UI Automation client will cast the GetPattern return value to the requested pattern interface whenever it is not null .

Si una clase de sistemas del mismo nivel hereda otro sistema del mismo nivel, y la generación de informes de patrones y compatibilidad necesaria ya se controla a través de la clase base, no es necesario implementar GetPatternCore.If a peer class inherits from another peer, and all necessary support and pattern reporting is already handled by the base class, implementing GetPatternCore isn't necessary. Por ejemplo, si estás implementando un control de intervalo que deriva de RangeBase, y tu sistema del mismo nivel deriva de RangeBaseAutomationPeer, ese sistema del mismo nivel se devuelve a sí mismo para PatternInterface.RangeValue y tiene implementaciones de trabajo de la interfaz IRangeValueProvider que admite el patrón.For example, if you are implementing a range control that derives from RangeBase, and your peer derives from RangeBaseAutomationPeer, that peer returns itself for PatternInterface.RangeValue and has working implementations of the IRangeValueProvider interface that supports the pattern.

Aunque no es el código literal, este ejemplo se aproxima a la implementación de GetPatternCore que ya está presente en RangeBaseAutomationPeer.Although it is not the literal code, this example approximates the implementation of GetPatternCore already present in RangeBaseAutomationPeer.

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    return base.GetPattern(patternInterface);
}

Si estás implementando un sistema del mismo nivel donde no tienes toda la compatibilidad que necesitas de una clase base del mismo nivel, o si quieres cambiar o incorporar al conjunto de modelos heredados de la base que tu sistema del mismo nivel puede admitir, debes invalidar GetPatternCore para permitir que los clientes de Automatización de la interfaz de usuario usen los modelos.If you are implementing a peer where you don't have all the support you need from a base peer class, or you want to change or add to the set of base-inherited patterns that your peer can support, then you should override GetPatternCore to enable UI Automation clients to use the patterns.

Para obtener una lista de los modelos de proveedores que están disponibles en la implementación UWP de la compatibilidad para la Automatización de la interfaz de usuario, consulta Windows.UI.Xaml.Automation.Provider.For a list of the provider patterns that are available in the UWP implementation of UI Automation support, see Windows.UI.Xaml.Automation.Provider. Cada uno de esos modelos tiene un valor correspondiente de la enumeración PatternInterface, que es cómo los clientes de Automatización de la interfaz de usuario solicitan el modelo en una llamada GetPattern.Each such pattern has a corresponding value of the PatternInterface enumeration, which is how UI Automation clients request the pattern in a GetPattern call.

Un sistema del mismo nivel puede informar que admite más de un patrón.A peer can report that it supports more than one pattern. En ese caso, la invalidación debería incluir lógica de ruta de acceso devuelta para cada valor PatternInterface admitido y devolver el sistema del mismo nivel en cada caso coincidente.If so, the override should include return path logic for each supported PatternInterface value and return the peer in each matching case. Se espera que el autor de la llamada solicite solo una interfaz por vez, y depende de él realizar la conversión a la interfaz esperada.It is expected that the caller will request only one interface at a time, and it is up to the caller to cast to the expected interface.

Este es un ejemplo de una invalidación GetPatternCore para un sistema del mismo nivel personalizado.Here's an example of a GetPatternCore override for a custom peer. Notifica la compatibilidad de dos patrones: IRangeValueProvider y IToggleProvider.It reports the support for two patterns, IRangeValueProvider and IToggleProvider. Este control es un control de visualización de medios que se puede mostrar en pantalla completa (modo de conmutación) y que tiene una barra de progreso en la que los usuarios pueden seleccionar una posición (el control de intervalo).The control here is a media display control that can display as full-screen (the toggle mode) and that has a progress bar within which users can select a position (the range control). Este código proviene del ejemplo de accesibilidad de XAML.This code came from the XAML accessibility sample.

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    else if (patternInterface == PatternInterface.Toggle)
    {
        return this;
    }
    return null;
}

Reenvío de patrones de subelementosForwarding patterns from sub-elements

Una implementación de método GetPatternCore también puede especificar un subelemento o una parte como un proveedor de patrones para su host.A GetPatternCore method implementation can also specify a sub-element or part as a pattern provider for its host. Este ejemplo imita el modo en que ItemsControl transfiere el control del patrón de desplazamiento al sistema del mismo nivel de su control ScrollViewer interno.This example mimics how ItemsControl transfers scroll-pattern handling to the peer of its internal ScrollViewer control. Para especificar un subelemento para el control de patrones, este código obtiene el objeto del subelemento, crea un sistema del mismo nivel para el subelemento con el método FrameworkElementAutomationPeer.CreatePeerForElement y devuelve el nuevo sistema del mismo nivel.To specify a sub-element for pattern handling, this code gets the sub-element object, creates a peer for the sub-element by using the FrameworkElementAutomationPeer.CreatePeerForElement method, and returns the new peer.

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.Scroll)
    {
        ItemsControl owner = (ItemsControl) base.Owner;
        UIElement itemsHost = owner.ItemsHost;
        ScrollViewer element = null;
        while (itemsHost != owner)
        {
            itemsHost = VisualTreeHelper.GetParent(itemsHost) as UIElement;
            element = itemsHost as ScrollViewer;
            if (element != null)
            {
                break;
            }
        }
        if (element != null)
        {
            AutomationPeer peer = FrameworkElementAutomationPeer.CreatePeerForElement(element);
            if ((peer != null) && (peer is IScrollProvider))
            {
                return (IScrollProvider) peer;
            }
        }
    }
    return base.GetPatternCore(patternInterface);
}

Otros métodos CoreOther Core methods

Tu control probablemente necesite admitir equivalentes de teclado para escenarios primarios. Para obtener más información acerca de por qué esto puede ser necesario, consulta Accesibilidad de teclado.Your control may need to support keyboard equivalents for primary scenarios; for more info about why this might be necessary, see Keyboard accessibility. La implementación de compatibilidad de teclado es necesariamente parte del código de control y no el código de sistemas del mismo nivel, porque eso es parte de la lógica de un control, pero tu clase de sistemas del mismo nivel debe invalidar los métodos GetAcceleratorKeyCore y GetAccessKeyCore para notificar a los clientes de Automatización de la interfaz de usuario qué claves se usan.Implementing the key support is necessarily part of the control code and not the peer code because that is part of a control's logic, but your peer class should override the GetAcceleratorKeyCore and GetAccessKeyCore methods to report to UI Automation clients which keys are used. Ten en cuenta que es posible que las cadenas que proporcionan información clave deban localizarse y, por consiguiente, deben provenir de recursos, en lugar de cadenas codificadas de forma rígida.Consider that the strings that report key information might need to be localized, and should therefore come from resources, not hard-coded strings.

Si estás proporcionando un sistema del mismo nivel para una clase que admite una colección, es mejor derivar de clases funcionales y clases del mismo nivel que ya cuenten con ese tipo de compatibilidad para colecciones.If you are providing a peer for a class that supports a collection, it's best to derive from both functional classes and peer classes that already have that kind of collection support. Si no puedes hacerlo, los sistemas del mismo nivel para controles que mantienen colecciones secundarias pueden tener que invalidar el método GetChildrenCore de los sistemas del mismo nivel relacionado con la colección para notificar correctamente las relaciones entre los elementos principales y los secundarios al árbol de Automatización de la interfaz de usuario.If you can't do so, peers for controls that maintain child collections may have to override the collection-related peer method GetChildrenCore to properly report the parent-child relationships to the UI Automation tree.

Implementa los métodos IsContentElementCore y IsControlElementCore para indicar si tu control incluye contenido de datos o cumple un rol interactivo en la interfaz de usuario (o ambas cosas).Implement the IsContentElementCore and IsControlElementCore methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). De manera predeterminada, ambos métodos devuelven el valor true .By default, both methods return true . Estas opciones de configuración mejoran la facilidad de uso de las tecnologías de asistencia como los lectores de pantalla, que pueden usar estos métodos para filtrar el árbol de automatización.These settings improve the usability of assistive technologies such as screen readers, which may use these methods to filter the automation tree. Si el método GetPatternCore transfiere el control del patrón a un subelemento del mismo nivel, el método IsControlElementCore del subelemento del mismo nivel puede devolver false para ocultar el subelemento del mismo nivel del árbol de automatización.If your GetPatternCore method transfers pattern handling to a sub-element peer, the sub-element peer's IsControlElementCore method can return false to hide the sub-element peer from the automation tree.

Algunos controles probablemente admitan escenarios de etiquetado, donde una parte de la etiqueta de texto proporciona información para una parte que no es de texto, o un control está destinado a formar parte de una relación de etiquetado conocida con otro control de la interfaz de usuario.Some controls may support labeling scenarios, where a text label part supplies information for a non-text part, or a control is intended to be in a known labeling relationship with another control in the UI. Si es posible proporcionar un comportamiento basado en clases útil, puedes invalidar GetLabeledByCore para hacerlo.If it's possible to provide a useful class-based behavior, you can override GetLabeledByCore to provide this behavior.

GetBoundingRectangleCore y GetClickablePointCore se usan principalmente para escenarios de pruebas automatizadas.GetBoundingRectangleCore and GetClickablePointCore are used mainly for automated testing scenarios. Si quieres admitir pruebas automatizadas para tu control, quizás quieras invalidar estos métodos.If you want to support automated testing for your control, you might want to override these methods. Esto podría ser deseable para controles del tipo de intervalo, en los que no puedes sugerir un único punto porque el lugar donde el usuario hace clic en el espacio de coordenadas tiene un efecto diferente en un intervalo.This might be desired for range-type controls, where you can't suggest just a single point because where the user clicks in coordinate space has a different effect on a range. Por ejemplo, el sistema de automatización del mismo nivel ScrollBar predeterminado invalida GetClickablePointCore para devolver un valor Point que "no es un número".For example, the default ScrollBar automation peer overrides GetClickablePointCore to return a "not a number" Point value.

GetLiveSettingCore influye el valor predeterminado del control de LiveSetting para la Automatización de la interfaz de usuario.GetLiveSettingCore influences the control default for the LiveSetting value for UI Automation. Quizás quieras invalidarlo si quieres que el control devuelva un valor diferente de AutomationLiveSetting.Off.You might want to override this if you want your control to return a value other than AutomationLiveSetting.Off. Para obtener más información sobre qué representa LiveSetting , consulte AutomationProperties. LiveSetting.For more info on what LiveSetting represents, see AutomationProperties.LiveSetting.

Podrías invalidar GetOrientationCore si tu control tiene una propiedad de orientación que pueda establecerse y que pueda asignarse a AutomationOrientation.You might override GetOrientationCore if your control has a settable orientation property that can map to AutomationOrientation. Las clases ScrollBarAutomationPeer y SliderAutomationPeer hacen esto.The ScrollBarAutomationPeer and SliderAutomationPeer classes do this.

Implementación base en FrameworkElementAutomationPeerBase implementation in FrameworkElementAutomationPeer

La implementación base de FrameworkElementAutomationPeer proporciona cierta información de Automatización de la interfaz de usuario que puede ser interpretada desde diversas propiedades de comportamiento y diseño que se definen en el nivel del marco.The base implementation of FrameworkElementAutomationPeer provides some UI Automation information that can be interpreted from various layout and behavior properties that are defined at the framework level.

  • GetBoundingRectangleCore: devuelve una estructura Rect basada en las características de diseño conocidas.GetBoundingRectangleCore: Returns a Rect structure based on the known layout characteristics. Devuelve un valor de 0 Rect si IsOffscreen es true .Returns a 0-value Rect if IsOffscreen is true .
  • GetClickablePointCore: devuelve la estructura Point basada en las características de diseño conocidas, siempre que exista un BoundingRectangle no nuloGetClickablePointCore: Returns a Point structure based on the known layout characteristics, as long as there is a nonzero BoundingRectangle .
  • GetNameCore: para conocer un comportamiento más amplio que el que puede resumirse aquí, consulta GetNameCore.GetNameCore: More extensive behavior than can be summarized here; see GetNameCore. Básicamente, intenta una conversión de cadena en cualquier contenido conocido de un ContentControl o clases relacionadas que tienen contenido.Basically, it attempts a string conversion on any known content of a ContentControl or related classes that have content. Además, si existe un valor para LabeledBy, ese valor Name del elemento se usa como NombreAlso, if there is a value for LabeledBy, that item's Name value is used as the Name .
  • HasKeyboardFocusCore: se evalúa en función de las propiedades FocusState e IsEnabled del propietario.HasKeyboardFocusCore: Evaluated based on the owner's FocusState and IsEnabled properties. Los elementos que no son controles siempre devuelven false .Elements that aren't controls always return false .
  • IsEnabledCore: se evalúa en función de la propiedad IsEnabled del propietario si es un Control.IsEnabledCore: Evaluated based on the owner's IsEnabled property if it is a Control. Los elementos que no son controles siempre devuelven true .Elements that aren't controls always return true . Esto no significa que el propietario esté habilitado en el sentido convencional de interacción; significa que el sistema del mismo nivel está habilitado a pesar de que el propietario no tiene una propiedad IsEnabled .This doesn't mean that the owner is enabled in the conventional interaction sense; it means that the peer is enabled despite the owner not having an IsEnabled property.
  • IsKeyboardFocusableCore: devuelve true si el propietario es un control; en caso contrario, es false .IsKeyboardFocusableCore: Returns true if owner is a Control; otherwise it is false .
  • IsOffscreenCore: Visibility de Collapsed en el elemento propietario o en cualquiera de sus elementos principales equivale a un valor true de IsOffscreen.IsOffscreenCore: A Visibility of Collapsed on the owner element or any of its parents equates to a true value for IsOffscreen. Excepción: un objeto Popup puede ser visible incluso si los elementos principales de su propietario no lo son.Exception: a Popup object can be visible even if its owner's parents are not.
  • SetFocusCore: llama al foco.SetFocusCore: Calls Focus.
  • GetParent: llama a FrameworkElement.Parent desde el propietario y busca el sistema del mismo nivel apropiado.GetParent: Calls FrameworkElement.Parent from the owner, and looks up the appropriate peer. Este no es un par de invalidación con un método "Core", por lo que no puedes cambiar este comportamiento.This isn't an override pair with a "Core" method, so you can't change this behavior.

Nota

Los sistemas del mismo nivel de UWP predeterminados implementan un comportamiento mediante el uso de código nativo interno que implementa UWP, no necesariamente mediante el uso del código real de UWP.Default UWP peers implement a behavior by using internal native code that implements the UWP, not necessarily by using actual UWP code. No podrás ver el código ni la lógica de la implementación a través de la reflexión de common language runtime (CLR) ni de otras técnicas.You won't be able to see the code or logic of the implementation through common language runtime (CLR) reflection or other techniques. Tampoco verás páginas de referencia diferentes en la referencia para invalidaciones específicas de la subclase del comportamiento de sistemas del mismo nivel base.You also won't see distinct reference pages for subclass-specific overrides of base peer behavior. Por ejemplo, probablemente exista comportamiento adicional para GetNameCore de TextBoxAutomationPeer, que no se describe en la página de referencia AutomationPeer.GetNameCore , pero no hay ninguna página de referencia para TextBoxAutomationPeer.GetNameCore .For example, there might be additional behavior for GetNameCore of a TextBoxAutomationPeer, which won't be described on the AutomationPeer.GetNameCore reference page, and there is no reference page for TextBoxAutomationPeer.GetNameCore . Ni siquiera existe una página de referencia de TextBoxAutomationPeer.GetNameCore .There isn't even a TextBoxAutomationPeer.GetNameCore reference page. En cambio, lee el tema de referencia sobre la clase de sistemas del mismo nivel más inmediata y busca notas de implementación en la sección de observaciones.Instead, read the reference topic for the most immediate peer class, and look for implementation notes in the Remarks section.

Sistemas del mismo nivel y AutomationPropertiesPeers and AutomationProperties

Tu sistema de automatización del mismo nivel debe proporcionar valores predeterminados adecuados para la información relativa a la accesibilidad de tu control.Your automation peer should provide appropriate default values for your control's accessibility-related information. Ten en cuenta que cualquier código de aplicación que use el control puede invalidar parte de ese comportamiento incluyendo los valores de propiedad adjunta AutomationProperties en instancias de control.Note that any app code that uses the control can override some of that behavior by including AutomationProperties attached-property values on control instances. Los autores de llamadas pueden hacer esto para los controles predeterminados o para los controles personalizados.Callers can do this either for the default controls or for custom controls. Por ejemplo, el siguiente XAML crea un botón que tiene dos propiedades de Automatización de la interfaz de usuario personalizadas: <Button AutomationProperties.Name="Special" AutomationProperties.HelpText="This is a special button."/>For example, the following XAML creates a button that has two customized UI Automation properties: <Button AutomationProperties.Name="Special" AutomationProperties.HelpText="This is a special button."/>

Para obtener más información sobre las propiedades adjuntas de AutomationProperties , consulte información básica de accesibilidad.For more info about AutomationProperties attached properties, see Basic accessibility information.

Algunos de los métodos AutomationPeer existen debido al contrato general relativo a cómo se espera que los proveedores de Automatización de la interfaz de usuario proporcionen información, pero estos métodos generalmente no se implementan en sistemas del mismo nivel del control.Some of the AutomationPeer methods exist because of the general contract of how UI Automation providers are expected to report information, but these methods are not typically implemented in control peers. Esto se debe a que se espera que los valores AutomationProperties aplicados al código de la aplicación que usa los controles en una interfaz de usuario específica proporcionen esa información.This is because that info is expected to be provided by AutomationProperties values applied to the app code that uses the controls in a specific UI. Por ejemplo, la mayoría de las aplicaciones definirían la relación de etiquetado entre dos controles diferentes de la interfaz de usuario aplicando un valor de AutomationProperties.LabeledBy.For example, most apps would define the labeling relationship between two different controls in the UI by applying a AutomationProperties.LabeledBy value. No obstante, LabeledByCore se implementa en ciertos sistemas del mismo nivel que representan relaciones de elementos o datos de un control, como el uso de una parte de encabezado para etiquetar una parte de campo de datos, el etiquetado de los elementos con sus contenedores o escenarios similares.However, LabeledByCore is implemented in certain peers that represent data or item relationships in a control, such as using a header part to label a data-field part, labeling items with their containers, or similar scenarios.

Implementación de patronesImplementing patterns

Veamos cómo escribir un sistema del mismo nivel para un control que implementa un comportamiento de expansión y contracción implementando la interfaz del patrón de control para expansión y contracción.Let's look at how to write a peer for a control that implements an expand-collapse behavior by implementing the control pattern interface for expand-collapse. El sistema del mismo nivel debería permitir la accesibilidad para el comportamiento de expansión y contracción devolviéndose a sí mismo siempre que se llame a GetPattern con un valor PatternInterface.ExpandCollapse.The peer should enable the accessibility for the expand-collapse behavior by returning itself whenever GetPattern is called with a value of PatternInterface.ExpandCollapse. El sistema del mismo nivel después hereda la interfaz de proveedor para ese patrón ( IExpandCollapseProvider) y proporciona implementaciones para cada uno de los miembros de esa interfaz de proveedor.The peer should then inherit the provider interface for that pattern ( IExpandCollapseProvider) and provide implementations for each of the members of that provider interface. En este caso, la interfaz tiene que invalidar tres miembros: Expand, Collapse y ExpandCollapseState.In this case the interface has three members to override: Expand, Collapse, ExpandCollapseState.

Es útil planear con tiempo la accesibilidad en el diseño de la API de la propia clase.It's helpful to plan ahead for accessibility in the API design of the class itself. Siempre que tengas un comportamiento que pueda llegar a ser solicitado por las interacciones típicas con un usuario que trabaja en la interfaz de usuario y también por medio de un patrón de proveedores de automatización, proporciona un solo método que pueda llamar el patrón de automatización o la respuesta de la interfaz de usuario.Whenever you have a behavior that is potentially requested either as a result of typical interactions with a user who is working in the UI or through an automation provider pattern, provide a single method that either the UI response or the automation pattern can call. Por ejemplo, si tu control tiene partes de botón que tienen controladores de eventos conectados que pueden expandir o contraer el control, y tiene equivalentes de teclado para esas acciones, haz que estos controladores de eventos llamen al mismo método al que llamas desde dentro del cuerpo de las implementaciones de Expand o Collapse para IExpandCollapseProvider en el sistema del mismo nivel.For example, if your control has button parts that have wired event handlers that can expand or collapse the control, and has keyboard equivalents for those actions, have these event handlers call the same method that you call from within the body of the Expand or Collapse implementations for IExpandCollapseProvider in the peer. Usar un método de lógica común también puede resultar útil para garantizar la actualización de los estados visuales de tu control a fin de mostrar estados lógicos de forma uniforme independientemente de cómo se haya invocado el comportamiento.Using a common logic method can also be a useful way to make sure that your control's visual states are updated to show logical state in a uniform way, regardless of how the behavior was invoked.

Una implementación típica es aquella en las que las API de proveedor primero llaman a Owner para acceder a la instancia de control en tiempo de ejecución.A typical implementation is that the provider APIs first call Owner for access to the control instance at run time. Después, pueden llamarse los métodos de comportamiento necesarios en ese objeto.Then the necessary behavior methods can be called on that object.

public class IndexCardAutomationPeer : FrameworkElementAutomationPeer, IExpandCollapseProvider {
    private IndexCard ownerIndexCard;
    public IndexCardAutomationPeer(IndexCard owner) : base(owner)
    {
         ownerIndexCard = owner;
    }
}

Una implementación alternativa es que el propio control pueda hacer referencia a su sistema del mismo nivel.An alternate implementation is that the control itself can reference its peer. Este es un patrón común si generas eventos de automatización desde el control, porque el método RaiseAutomationEvent es un método del sistema del mismo nivel.This is a common pattern if you are raising automation events from the control, because the RaiseAutomationEvent method is a peer method.

Eventos de automatización de la interfaz de usuarioUI Automation events

Los eventos de Automatización de la interfaz de usuario pueden clasificarse de la siguiente manera.UI Automation events fall into the following categories.

EventoEvent DescripciónDescription
Cambio de propiedadProperty change Se desencadena cuando cambia una propiedad de un patrón de control o un elemento de automatización de la interfaz de usuario.Fires when a property on a UI Automation element or control pattern changes. Por ejemplo, si un cliente necesita supervisar el control de casilla de una aplicación, puede registrarse para escuchar un evento de cambio de propiedades en la propiedad ToggleState.For example, if a client needs to monitor an app's check box control, it can register to listen for a property change event on the ToggleState property. Cuando el control de casilla se activa o desactiva, el proveedor inicia el evento y el cliente puede actuar de la manera que sea necesaria.When the check box control is checked or unchecked, the provider fires the event and the client can act as necessary.
Acción de elementoElement action Se desencadena cuando un cambio en la interfaz de usuario se origina en la actividad programática o del usuario. Por ejemplo, cuando se hace clic en un botón o se invoca a través del patrón Invoke .Fires when a change in the UI results from user or programmatic activity; for example, when a button is clicked or invoked through the Invoke pattern.
Cambio de estructuraStructure change Se desencadena cuando cambia la estructura del árbol de Automatización de la interfaz de usuario.Fires when the structure of the UI Automation tree changes. La estructura cambia cuando se hacen visibles, ocultan o quitan elementos nuevos de la interfaz de usuario en el escritorio.The structure changes when new UI items become visible, hidden, or removed on the desktop.
Cambio globalGlobal change Se desencadena cuando se producen acciones de interés global para el cliente, como cuando el foco cambia desde un elemento a otro o cuando se cierra una ventana secundaria.Fires when actions of global interest to the client occur, such as when the focus shifts from one element to another, or when a child window closes. Algunos eventos no implican necesariamente un cambio en el estado de la UI.Some events do not necessarily mean that the state of the UI has changed. Por ejemplo, si el usuario presiona un campo de entrada de texto y después hace clic en un botón para actualizar el campo, se desencadena un evento TextChanged si el usuario no cambió el texto.For example, if the user tabs to a text-entry field and then clicks a button to update the field, a TextChanged event fires even if the user did not actually change the text. Al procesar un evento, puede ser necesario que la aplicación cliente compruebe si realmente se ha producido un cambio antes de realizar cualquier acción.When processing an event, it may be necessary for a client application to check whether anything has actually changed before taking action.

Identificadores de AutomationEventsAutomationEvents identifiers

Los eventos de Automatización de la interfaz de usuario están definidos por los valores AutomationEvents.UI Automation events are identified by AutomationEvents values. Los valores de la enumeración identifican unívocamente el tipo de evento.The values of the enumeration uniquely identify the kind of event.

Provocar eventosRaising events

Los clientes de automatización de la interfaz de usuario pueden suscribirse a eventos de automatización.UI Automation clients can subscribe to automation events. En el modelo de sistemas de automatización del mismo nivel, los sistemas de automatización del mismo nivel para los controles personalizados deben informar de los cambios en el estado del control que sean pertinentes a la accesibilidad llamando al método RaiseAutomationEvent.In the automation peer model, peers for custom controls must report changes to control state that are relevant to accessibility by calling the RaiseAutomationEvent method. De manera similar, cuando cambia un valor clave de una propiedad de Automatización de la interfaz de usuario, los sistemas de control personalizado del mismo nivel deben llamar al método RaisePropertyChangedEvent.Similarly, when a key UI Automation property value changes, custom control peers should call the RaisePropertyChangedEvent method.

El siguiente ejemplo de código muestra cómo obtener el objeto del sistema del mismo nivel del código de definición de control y llamar a un método para desencadenar un evento desde ese sistema del mismo nivel.The next code example shows how to get the peer object from within the control definition code and call a method to fire an event from that peer. Con fines de optimización, el código determina si hay escuchas para este tipo de evento.As an optimization, the code determines whether there are any listeners for this event type. Desencadenar el evento y crear el objeto del mismo nivel solo cuando hay escuchas evita sobrecargas innecesarias y ayuda al control a mantener su capacidad de respuesta.Firing the event and creating the peer object only when there are listeners avoids unnecessary overhead and helps the control remain responsive.

if (AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged))
{
    NumericUpDownAutomationPeer peer =
        FrameworkElementAutomationPeer.FromElement(nudCtrl) as NumericUpDownAutomationPeer;
    if (peer != null)
    {
        peer.RaisePropertyChangedEvent(
            RangeValuePatternIdentifiers.ValueProperty,
            (double)oldValue,
            (double)newValue);
    }
}

Navegación de sistemas del mismo nivelPeer navigation

Después de localizar un sistema de automatización del mismo nivel, un cliente de Automatización de la interfaz de usuario puede navegar por la estructura del mismo nivel de una aplicación llamando a los métodos GetChildren y GetParent del objeto del sistema de mismo nivel.After locating an automation peer, a UI Automation client can navigate the peer structure of an app by calling the peer object's GetChildren and GetParent methods. La implementación del método GetChildrenCore del sistema del mismo nivel admite la navegación entre elementos de la interfaz de usuario dentro de un control.Navigation among UI elements within a control is supported by the peer's implementation of the GetChildrenCore method. El sistema de Automatización de la interfaz de usuario llama a este método para crear un árbol de los subelementos incluidos dentro de un control, por ejemplo, elementos de lista en un cuadro de lista.The UI Automation system calls this method to build up a tree of sub-elements contained within a control; for example, list items in a list box. El método GetChildrenCore en FrameworkElementAutomationPeer recorre el árbol visual de elementos para crear el árbol de sistemas de automatización del mismo nivel.The default GetChildrenCore method in FrameworkElementAutomationPeer traverses the visual tree of elements to build the tree of automation peers. Los controles personalizados pueden invalidar este método para exponer una representación diferente de los elementos secundarios a los clientes de automatización, lo que devuelve los sistemas de automatización del mismo nivel de los elementos que transmiten información o permiten la interacción del usuario.Custom controls can override this method to expose a different representation of child elements to automation clients, returning the automation peers of elements that convey information or allow user interaction.

Compatibilidad de automatización nativa para patrones de textoNative automation support for text patterns

Algunos sistemas de automatización del mismo nivel predeterminados de las aplicaciones para UWP admiten patrones de control para el patrón de texto ( PatternInterface.Text).Some of the default UWP app automation peers provide control pattern support for the text pattern ( PatternInterface.Text). Sin embargo, esta compatibilidad se ofrece mediante métodos nativos y los sistemas de automatización del mismo nivel no anotarán la interfaz ITextProvider en la herencia (administrada).But they provide this support through native methods, and the peers involved won't note the ITextProvider interface in the (managed) inheritance. Aun así, si un cliente de Automatización de la interfaz de usuario administrado o no administrado solicita patrones al sistema de automatización del mismo nivel, notificará la compatibilidad con el patrón de texto y proporcionará el comportamiento de partes del patrón cuando se llame a las API del cliente.Still, if a managed or non-managed UI Automation client queries the peer for patterns, it will report support for the text pattern, and provide behavior for parts of the pattern when client APIs are called.

Si tienes intención de derivar desde uno de los controles de texto de la aplicación para UWP y crear también un sistema del mismo nivel personalizado que derive de uno de los sistemas del mismo nivel relacionados con el texto, comprueba las secciones Observaciones del sistema del mismo nivel para informarte sobre la compatibilidad de nivel nativo con los patrones.If you intend to derive from one of the UWP app text controls and also create a custom peer that derives from one of the text-related peers, check the Remarks sections for the peer to learn more about any native-level support for patterns. Puedes acceder al comportamiento de base nativa en el sistema del mismo nivel personalizado si llamas a la implementación base desde las implementaciones de la interfaz del proveedor administrado, pero es difícil modificar lo que hace la implementación base porque las interfaces nativas en el sistema del mismo nivel y su control propietario no están expuestas.You can access the native base behavior in your custom peer if you call the base implementation from your managed provider interface implementations, but it's difficult to modify what the base implementation does because the native interfaces on both the peer and its owner control aren't exposed. Generalmente usarás las implementaciones base tal cual (solo llamada a la base) o reemplazarás por completo la funcionalidad con tu propio código administrado y no llamarás a la implementación base.Generally you should either use the base implementations as-is (call base only) or completely replace the functionality with your own managed code and don't call the base implementation. Este es un escenario avanzado. Necesitarás estar muy familiarizado con el marco de servicios de texto que usa tu control para poder admitir los requisitos de accesibilidad al usar ese marco.The latter is an advanced scenario, you'll need good familiarity with the text services framework being used by your control in order to support the accessibility requirements when using that framework.

AutomationProperties.AccessibilityViewAutomationProperties.AccessibilityView

Además de proporcionar un sistema del mismo nivel personalizado, también puedes ajustar la representación de la vista de árbol para cualquier instancia de control, estableciendo AutomationProperties.AccessibilityView en XAML.In addition to providing a custom peer, you can also adjust the tree view representation for any control instance, by setting AutomationProperties.AccessibilityView in XAML. Esto no se implementa como parte de una clase del mismo nivel, pero lo mencionamos aquí porque está relacionado con la compatibilidad para accesibilidad general ya sea para controles personalizados o para las plantillas que personalices.This isn't implemented as part of a peer class, but we'll mention it here because it's germane to overall accessibility support either for custom controls or for templates you customize.

El principal escenario de uso de AutomationProperties.AccessibilityView es omitir deliberadamente determinados controles de una plantilla de las vistas de Automatización de la interfaz de usuario, porque no contribuyen de forma significativa a la vista de accesibilidad de todo el control.The main scenario for using AutomationProperties.AccessibilityView is to deliberately omit certain controls in a template from the UI Automation views, because they don't meaningfully contribute to the accessibility view of the entire control. Para evitar esto, establece AutomationProperties.AccessibilityView en "Raw".To prevent this, set AutomationProperties.AccessibilityView to "Raw".

Iniciar excepciones desde sistemas de automatización del mismo nivelThrowing exceptions from automation peers

Las API que implementas para la compatibilidad del sistema de automatización del mismo nivel pueden generar excepciones.The APIs that you are implementing for your automation peer support are permitted to throw exceptions. Se espera que cualquier cliente de automatización de la interfaz de usuario que está escuchando sea lo suficientemente sólido como para continuar después de que se inicien la mayoría de las excepciones.It's expected any UI Automation clients that are listening are robust enough to continue on after most exceptions are thrown. Con toda probabilidad, el agente de escucha está mirando hacia un árbol de automatización vertical que incluye aplicaciones distintas de la tuya y es un diseño de cliente inaceptable para traer el cliente completo, solo porque un área del árbol inició una excepción basada en el sistema del mismo nivel cuando el cliente llamó a sus API.In all likelihood that listener is looking at an all-up automation tree that includes apps other than your own, and it's an unacceptable client design to bring down the entire client just because one area of the tree threw a peer-based exception when the client called its APIs.

Para los parámetros que se pasan en tu sistema del mismo nivel, se puede validar la entrada y, por ejemplo, iniciar ArgumentNullException si se pasó null y eso no es un valor válido para tu implementación.For parameters that are passed in to your peer, it's acceptable to validate the input, and for example throw ArgumentNullException if it was passed null and that's not a valid value for your implementation. Sin embargo, si el sistema del mismo nivel realiza operaciones posteriores, recuerda que las interacciones del sistema del mismo nivel con el control de hospedaje tienen cierto carácter asíncrono.However, if there are subsequent operations performed by your peer, remember that the peer's interactions with the hosting control have something of an asynchronous character to them. Cualquier cosa que haga un sistema del mismo nivel no bloqueará necesariamente el umbral de la interfaz de usuario en el control (y probablemente no debería).Anything a peer does won't necessarily block the UI thread in the control (and it probably shouldn't). Así que podrías tener situaciones en las que un objeto estaba disponible o tenía ciertas propiedades cuando se creó el sistema del mismo nivel o cuando se llamó por primera vez a un método de sistema de automatización del mismo nivel, pero mientras tanto, el estado del control ha cambiado.So you could have situations where an object was available or had certain properties when the peer was created or when an automation peer method was first called, but in the meantime the control state has changed. Para estos casos, hay dos excepciones dedicadas que un proveedor puede iniciar:For these cases, there are two dedicated exceptions that a provider can throw:

  • Inicia ElementNotAvailableException si no puedes acceder al propietario del sistema del mismo nivel o a un elemento relacionado del sistema del mismo nivel, basado en la información original que pasó tu API.Throw ElementNotAvailableException if you're unable to access either the peer's owner or a related peer element based on the original info your API was passed. Por ejemplo, puede que tengas un sistema del mismo nivel que está intentando ejecutar sus métodos pero el propietario se ha eliminado de la interfaz de usuario, como un cuadro de diálogo modal que se ha cerrado.For example, you might have a peer that's trying to run its methods but the owner has since been removed from the UI, such as a modal dialog that's been closed. Para un cliente de non-.NET, se asigna a UIA _ E _ ELEMENTNOTAVAILABLE.For a non-.NET client, this maps to UIA_E_ELEMENTNOTAVAILABLE.
  • Inicia ElementNotEnabledException si todavía hay un propietario, pero se encuentra en un modo como IsEnabled=false , que está bloqueando algunos de los cambios de programación específicos que el sistema del mismo nivel está intentando cumplir.Throw ElementNotEnabledException if there still is an owner, but that owner is in a mode such as IsEnabled=false that's blocking some of the specific programmatic changes that your peer is trying to accomplish. Para un cliente de non-.NET, se asigna a UIA _ E _ ELEMENTNOTENABLED.For a non-.NET client, this maps to UIA_E_ELEMENTNOTENABLED.

Más allá de esto, los sistemas del mismo nivel deberían ser relativamente conservadores en cuanto a las excepciones que inician desde su compatibilidad con el sistema del mismo nivel.Beyond this, peers should be relatively conservative regarding exceptions that they throw from their peer support. La mayoría de los clientes no podrá controlar excepciones procedentes de sistemas del mismo nivel y convertirlas en opciones que se puedan accionar y que puedan ser elegidas por los usuarios cuando interaccionen con el cliente.Most clients won't be able to handle exceptions from peers and turn these into actionable choices that their users can make when interacting with the client. Así que, a veces, capturar excepciones sin volver a iniciarlas dentro de las implementaciones del mismo nivel puede suponer una estrategia más acertada que iniciar excepciones cada vez que no funciona algo que el sistema del mismo nivel intenta hacer.So sometimes a no-op, and catching exceptions without rethrowing within your peer implementations, is a better strategy than is throwing exceptions every time something the peer tries to do doesn't work. Ten en cuenta también que la mayoría de los clientes de Automatización de la interfaz de usuario no se escriben en código administrado.Consider also that most UI Automation clients aren't written in managed code. La mayoría están escritas en COM y simplemente están comprobando si hay elementos _ correctos en un valor HRESULT cada vez que llaman a un método de cliente de automatización de la interfaz de usuario que termina de obtener acceso al mismo nivel.Most are written in COM and are just checking for S_OK in an HRESULT whenever they call a UI Automation client method that ends up accessing your peer.