Propiedades de automatización en Xamarin.FormsAutomation Properties in Xamarin.Forms

Descargar ejemplo Descargar el ejemploDownload Sample Download the sample

Xamarin.Forms permite que los valores de accesibilidad se establezcan en elementos de la interfaz de usuario mediante el uso de las propiedades adjuntas de la clase AutomationProperties, que a su vez establece valores de accesibilidad nativa. Este artículo explica cómo usar la clase AutomationProperties, para que un lector de pantalla pueda leer los elementos en la página.Xamarin.Forms allows accessibility values to be set on user interface elements by using attached properties from the AutomationProperties class, which in turn set native accessibility values. This article explains how to use the AutomationProperties class, so that a screen reader can speak about the elements on the page.

Xamarin.Forms permite que las propiedades de automatización se establezcan en elementos de la interfaz de usuario a través de las propiedades adjuntas siguientes:Xamarin.Forms allows automation properties to be set on user interface elements via the following attached properties:

  • AutomationProperties.IsInAccessibleTree: indica si el elemento está disponible para una aplicación accesible.AutomationProperties.IsInAccessibleTree – indicates whether the element is available to an accessible application. Para obtener más información, consulte AutomationProperties.IsInAccessibleTree.For more information, see AutomationProperties.IsInAccessibleTree.
  • AutomationProperties.Name: una breve descripción del elemento que actúa como un identificador con capacidad de lectura para el elemento.AutomationProperties.Name – a short description of the element that serves as a speakable identifier for the element. Para obtener más información, consulte AutomationProperties.Name.For more information, see AutomationProperties.Name.
  • AutomationProperties.HelpText: una descripción más larga del elemento, que puede considerarse como el texto de información sobre herramientas asociado al elemento.AutomationProperties.HelpText – a longer description of the element, which can be thought of as tooltip text associated with the element. Para obtener más información, consulte AutomationProperties.HelpText.For more information, see AutomationProperties.HelpText.
  • AutomationProperties.LabeledBy: permite que otro elemento defina la información de accesibilidad para el elemento actual.AutomationProperties.LabeledBy – allows another element to define accessibility information for the current element. Para obtener más información, consulte AutomationProperties.LabeledBy.For more information, see AutomationProperties.LabeledBy.

Estas propiedades adjuntas establecen los valores de accesibilidad nativa para que un lector de pantalla pueda leer el elemento.These attached properties set native accessibility values so that a screen reader can speak about the element. Para más información sobre las propiedades adjuntas, consulte Propiedades asociadas.For more information about attached properties, see Attached Properties.

Importante

El uso de las propiedades adjuntas AutomationProperties puede afectar a la ejecución de prueba de IU en Android.Using the AutomationProperties attached properties may impact UI Test execution on Android. Las propiedades AutomationId, AutomationProperties.Name y AutomationProperties.HelpText, establecen la propiedad ContentDescription nativa, con los valores de propiedad AutomationProperties.Name y AutomationProperties.HelpText con prioridad sobre el valor AutomationId (si tanto AutomationProperties.Name como AutomationProperties.HelpText están establecidos, los valores se concatenarán).The AutomationId, AutomationProperties.Name and AutomationProperties.HelpText properties will both set the native ContentDescription property, with the AutomationProperties.Name and AutomationProperties.HelpText property values taking precedence over the AutomationId value (if both AutomationProperties.Name and AutomationProperties.HelpText are set, the values will be concatenated). Esto significa que cualquier prueba que busque AutomationId fallará si AutomationProperties.Name o AutomationProperties.HelpText también están establecidos en el elemento.This means that any tests looking for AutomationId will fail if AutomationProperties.Name or AutomationProperties.HelpText are also set on the element. En este escenario, las pruebas de IU deben modificarse para buscar el valor de AutomationProperties.Name o AutomationProperties.HelpText, o una concatenación de ambos.In this scenario, UI Tests should be altered to look for the value of AutomationProperties.Name or AutomationProperties.HelpText, or a concatenation of both.

Cada plataforma tiene un lector de pantalla diferente para leer los valores de accesibilidad:Each platform has a different screen reader to narrate the accessibility values:

Sin embargo, el comportamiento exacto de un lector de pantalla depende del software y de la configuración del usuario en él.However, the exact behavior of a screen reader depends on the software and on the user's configuration of it. Por ejemplo, la mayoría de los lectores de pantalla leen el texto asociado con un control cuando queda focalizado, permitiendo a los usuarios orientarse a medida que se mueven entre los controles en la página.For example, most screen readers read the text associated with a control when it receives focus, enabling users to orient themselves as they move among the controls on the page. Algunos lectores de pantalla leen también la interfaz de usuario de la aplicación completa cuando aparece una página, lo cual permite que el usuario reciba todo de contenido informativo disponible de la página antes de intentar navegar por ella.Some screen readers also read the entire application user interface when a page appears, which enables the user to receive all of the page's available informational content before attempting to navigate it.

Los lectores de pantalla también leen valores de accesibilidad distintos.Screen readers also read different accessibility values. En la aplicación de ejemplo:In the sample application:

  • VoiceOver leerá el valor Placeholder de Entry, seguido de las instrucciones para usar el control.VoiceOver will read the Placeholder value of the Entry, followed by instructions for using the control.
  • TalkBack leerá el valor Placeholder de Entry, seguido del valor AutomationProperties.HelpText, seguido de las instrucciones para usar el control.TalkBack will read the Placeholder value of the Entry, followed by the AutomationProperties.HelpText value, followed by instructions for using the control.
  • El Narrador leerá el valor AutomationProperties.LabeledBy de Entry, seguido de las instrucciones para usar el control.Narrator will read the AutomationProperties.LabeledBy value of the Entry, followed by instructions on using the control.

Además, el Narrador dará prioridad a AutomationProperties.Name, AutomationProperties.LabeledBy y, a continuación, AutomationProperties.HelpText.In addition, Narrator will prioritize AutomationProperties.Name, AutomationProperties.LabeledBy, and then AutomationProperties.HelpText. En Android, TalkBack puede combinar los valores AutomationProperties.Name y AutomationProperties.HelpText.On Android, TalkBack may combine the AutomationProperties.Name and AutomationProperties.HelpText values. Por lo tanto, se recomienda llevar a cabo pruebas de accesibilidad exhaustivas en cada plataforma para garantizar una experiencia óptima.Therefore, it's recommended that thorough accessibility testing is carried out on each platform to ensure an optimal experience.

AutomationProperties.IsInAccessibleTreeAutomationProperties.IsInAccessibleTree

La propiedad adjunta AutomationProperties.IsInAccessibleTree es un valor boolean que determina si el elemento es accesible, y por lo tanto visible, para los lectores de pantalla.The AutomationProperties.IsInAccessibleTree attached property is a boolean that determines if the element is accessible, and hence visible, to screen readers. Debe establecerse en true para usar las otras propiedades adjuntas de accesibilidad.It must be set to true to use the other accessibility attached properties. Esto se puede lograr en XAML de la siguiente manera:This can be accomplished in XAML as follows:

<Entry AutomationProperties.IsInAccessibleTree="true" />

Como alternativa, puede establecerse en C# de la siguiente manera:Alternatively, it can be set in C# as follows:

var entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);

Nota

Tenga en cuenta que el método SetValue también se puede utilizar para establecer la propiedad adjunta de AutomationProperties.IsInAccessibleTree, entry.SetValue(AutomationProperties.IsInAccessibleTreeProperty, true);Note that the SetValue method can also be used to set the AutomationProperties.IsInAccessibleTree attached property – entry.SetValue(AutomationProperties.IsInAccessibleTreeProperty, true);

AutomationProperties.NameAutomationProperties.Name

El valor de la propiedad adjunta AutomationProperties.Name debe ser una cadena de texto corta y descriptiva que usa un lector de pantalla anunciar un elemento.The AutomationProperties.Name attached property value should be a short, descriptive text string that a screen reader uses to announce an element. Esta propiedad debe establecerse para los elementos que tengan un significado que sea importante para comprender el contenido o interactuar con la interfaz de usuario.This property should be set for elements that have a meaning that is important for understanding the content or interacting with the user interface. Esto se puede lograr en XAML de la siguiente manera:This can be accomplished in XAML as follows:

<ActivityIndicator AutomationProperties.IsInAccessibleTree="true"
                   AutomationProperties.Name="Progress indicator" />

Como alternativa, puede establecerse en C# de la siguiente manera:Alternatively, it can be set in C# as follows:

var activityIndicator = new ActivityIndicator();
AutomationProperties.SetIsInAccessibleTree(activityIndicator, true);
AutomationProperties.SetName(activityIndicator, "Progress indicator");

Nota

Tenga en cuenta que el método SetValue también se puede utilizar para establecer la propiedad adjunta de AutomationProperties.Name, activityIndicator.SetValue(AutomationProperties.NameProperty, "Progress indicator");Note that the SetValue method can also be used to set the AutomationProperties.Name attached property – activityIndicator.SetValue(AutomationProperties.NameProperty, "Progress indicator");

AutomationProperties.HelpTextAutomationProperties.HelpText

La propiedad adjunta de AutomationProperties.HelpText debe establecerse en el texto que describe el elemento de interfaz de usuario y puede ser considerarse el texto de información sobre herramientas asociado al elemento.The AutomationProperties.HelpText attached property should be set to text that describes the user interface element, and can be thought of as tooltip text associated with the element. Esto se puede lograr en XAML de la siguiente manera:This can be accomplished in XAML as follows:

<Button Text="Toggle ActivityIndicator"
        AutomationProperties.IsInAccessibleTree="true"
        AutomationProperties.HelpText="Tap to toggle the activity indicator" />

Como alternativa, puede establecerse en C# de la siguiente manera:Alternatively, it can be set in C# as follows:

var button = new Button { Text = "Toggle ActivityIndicator" };
AutomationProperties.SetIsInAccessibleTree(button, true);
AutomationProperties.SetHelpText(button, "Tap to toggle the activity indicator");

Nota

Tenga en cuenta que el método SetValue también se puede utilizar para establecer la propiedad adjunta de AutomationProperties.HelpText, button.SetValue(AutomationProperties.HelpTextProperty, "Tap to toggle the activity indicator");Note that the SetValue method can also be used to set the AutomationProperties.HelpText attached property – button.SetValue(AutomationProperties.HelpTextProperty, "Tap to toggle the activity indicator");

En algunas plataformas, para editar controles, como un elemento Entry, la propiedad HelpText a veces puede omitirse y reemplazarse por el texto de marcador de posición.On some platforms, for edit controls such as an Entry, the HelpText property can sometimes be omitted and replaced with placeholder text. Por ejemplo, "Escriba aquí su nombre" es un buen candidato para la propiedad Entry.Placeholder que coloca el texto en el control antes de la entrada real del usuario.For example, "Enter your name here" is a good candidate for the Entry.Placeholder property that places the text in the control prior to the user's actual input.

AutomationProperties.LabeledByAutomationProperties.LabeledBy

La propiedad adjunta AutomationProperties.LabeledBy permite que otro elemento defina la información de accesibilidad para el elemento actual.The AutomationProperties.LabeledBy attached property allows another element to define accessibility information for the current element. Por ejemplo, un elemento Label junto a un elemento Entry puede utilizarse para describir lo que representa Entry.For example, a Label next to an Entry can be used to describe what the Entry represents. Esto se puede lograr en XAML de la siguiente manera:This can be accomplished in XAML as follows:

<Label x:Name="label" Text="Enter your name: " />
<Entry AutomationProperties.IsInAccessibleTree="true"
       AutomationProperties.LabeledBy="{x:Reference label}" />

Como alternativa, puede establecerse en C# de la siguiente manera:Alternatively, it can be set in C# as follows:

var nameLabel = new Label { Text = "Enter your name: " };
var entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);
AutomationProperties.SetLabeledBy(entry, nameLabel);

Nota

Tenga en cuenta que el método SetValue también se puede utilizar para establecer la propiedad adjunta de AutomationProperties.IsInAccessibleTree, entry.SetValue(AutomationProperties.LabeledByProperty, nameLabel);Note that the SetValue method can also be used to set the AutomationProperties.IsInAccessibleTree attached property – entry.SetValue(AutomationProperties.LabeledByProperty, nameLabel);

Pormenores relativos a la accesibilidadAccessibility intricacies

En las secciones siguientes se describen los pormenores que supone el hecho de establecer valores de accesibilidad en ciertos controles.The following sections describe the intricacies of setting accessibility values on certain controls.

En Android, para establecer el texto que el lector de pantalla leerá para la flecha Atrás de la barra de acciones NavigationPage, defina las propiedades AutomationProperties.Name y AutomationProperties.HelpText en Page.On Android, to set the text that screen readers will read for the back arrow in the action bar in a NavigationPage, set the AutomationProperties.Name and AutomationProperties.HelpText properties on a Page. Sin embargo, tenga en cuenta que esto no se aplicará a los botones Atrás del sistema operativo.However, note that this will not have an effect on OS back buttons.

MasterDetailPageMasterDetailPage

En iOS y la Plataforma Universal de Windows (UWP), para establecer el texto que el lector de pantalla leerá para el botón de alternancia en MasterDetailPage, defina las propiedades AutomationProperties.Name y AutomationProperties.HelpText en MasterDetailPage, o bien en la propiedad IconImageSource de la página Master.On iOS and the Universal Windows Platform (UWP), to set the text that screen readers will read for the toggle button on a MasterDetailPage, either set the AutomationProperties.Name, and AutomationProperties.HelpText properties on the MasterDetailPage, or on the IconImageSource property of the Master page.

En Android, para establecer el texto que el lector de pantalla leerá para el botón de alternancia en MasterDetailPage, agregue los recursos de cadena al proyecto de Android:On Android, to set the text that screen readers will read for the toggle button on a MasterDetailPage, add string resources to the Android project:

<resources>
    <string name="app_name">Xamarin Forms Control Gallery</string>
    <string name="btnMDPAutomationID_open">Open Side Menu message</string>
    <string name="btnMDPAutomationID_close">Close Side Menu message</string>
</resources>

A continuación, defina la AutomationId propiedad de la propiedad IconImageSource de la página Master en la cadena que corresponda:Then set the AutomationId property of the IconImageSource property of the Master page to the appropriate string:

var master = new ContentPage { ... };
master.IconImageSource.AutomationId = "btnMDPAutomationID";

ToolbarItemToolbarItem

En iOS, Android y UWP, los lectores de pantalla leerán el valor de propiedad Text de las instancias de ToolbarItem, siempre que no haya definido los valores AutomationProperties.Name y AutomationProperties.HelpText.On iOS, Android, and UWP, screen readers will read the Text property value of ToolbarItem instances, provided that AutomationProperties.Name or AutomationProperties.HelpText values aren't defined.

En iOS y UWP, el valor de propiedad AutomationProperties.Name reemplazará el valor de propiedad Text que el lector de pantalla lee.On iOS and UWP the AutomationProperties.Name property value will replace the Text property value that is read by the screen reader.

En Android, los valores de propiedad AutomationProperties.Name o AutomationProperties.HelpText reemplazarán por completo el valor de propiedad Text, que es visible y el lector de pantalla leerá.On Android, the AutomationProperties.Name and/or AutomationProperties.HelpText property values will completely replace the Text property value that is both visible and read by the screen reader. Tenga en cuenta que se trata de una limitación de API inferior a 26.Note that this is a limitation of APIs less than 26.