Propiedades de automatización de Xamarin.Forms

  • Artículo

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 permite que las propiedades de automatización se establezcan en elementos de la interfaz de usuario a través de las propiedades adjuntas siguientes:

  • AutomationProperties.IsInAccessibleTree: indica si el elemento está disponible para una aplicación accesible. Para obtener más información, consulte AutomationProperties.IsInAccessibleTree.
  • AutomationProperties.Name: una breve descripción del elemento que actúa como un identificador con capacidad de lectura para el elemento. Para obtener más información, consulte 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. Para obtener más información, consulte AutomationProperties.HelpText.
  • AutomationProperties.LabeledBy: permite que otro elemento defina la información de accesibilidad para el elemento actual. Para obtener más información, consulte AutomationProperties.LabeledBy.

Estas propiedades adjuntas establecen los valores de accesibilidad nativa para que un lector de pantalla pueda leer el elemento. Para más información sobre las propiedades adjuntas, consulte Propiedades asociadas.

Importante

El uso de las propiedades adjuntas AutomationProperties puede afectar a la ejecución de prueba de IU en 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). Esto significa que cualquier prueba que busque AutomationId fallará si AutomationProperties.Name o AutomationProperties.HelpText también están establecidos en el elemento. 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.

Cada plataforma tiene un lector de pantalla diferente para leer los valores de accesibilidad:

Sin embargo, el comportamiento exacto de un lector de pantalla depende del software y de la configuración del usuario en él. 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. 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.

Los lectores de pantalla también leen valores de accesibilidad distintos. En la aplicación de ejemplo:

  • VoiceOver leerá el valor Placeholder de Entry, seguido de las instrucciones para usar el control.
  • TalkBack leerá el valor Placeholder de Entry, seguido del valor AutomationProperties.HelpText, seguido de las instrucciones para usar el control.
  • El Narrador leerá el valor AutomationProperties.LabeledBy de Entry, seguido de las instrucciones para usar el control.

Además, el Narrador dará prioridad a AutomationProperties.Name, AutomationProperties.LabeledBy y, a continuación, AutomationProperties.HelpText. En Android, TalkBack puede combinar los valores AutomationProperties.Name y AutomationProperties.HelpText. Por lo tanto, se recomienda llevar a cabo pruebas de accesibilidad exhaustivas en cada plataforma para garantizar una experiencia óptima.

AutomationProperties.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. Debe establecerse en true para usar las otras propiedades adjuntas de accesibilidad. Esto se puede lograr en XAML de la siguiente manera:

<Entry AutomationProperties.IsInAccessibleTree="true" />

Como alternativa, puede establecerse en C# de la siguiente manera:

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

AutomationProperties.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. 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. Esto se puede lograr en XAML de la siguiente manera:

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

Como alternativa, puede establecerse en C# de la siguiente manera:

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");

AutomationProperties.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. Esto se puede lograr en XAML de la siguiente manera:

<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:

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");

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. 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.

AutomationProperties.LabeledBy

La propiedad adjunta AutomationProperties.LabeledBy permite que otro elemento defina la información de accesibilidad para el elemento actual. Por ejemplo, un elemento Label junto a un elemento Entry puede utilizarse para describir lo que representa Entry. Esto se puede lograr en XAML de la siguiente manera:

<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:

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

Importante

Todavía no se admite AutomationProperties.LabeledByProperty en iOS.

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

Pormenores relativos a la accesibilidad

En las secciones siguientes se describen los pormenores que supone el hecho de establecer valores de accesibilidad en ciertos controles.

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. Sin embargo, tenga en cuenta que esto no se aplicará a los botones Atrás del sistema operativo.

FlyoutPage

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 FlyoutPage, defina las propiedades AutomationProperties.Name y AutomationProperties.HelpText en FlyoutPage, o bien en la propiedad IconImageSource de la página Flyout.

En Android, para establecer el texto que el lector de pantalla leerá para el botón de alternancia en FlyoutPage, agregue los recursos de cadena al proyecto de Android:

<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 Flyout en la cadena que corresponda:

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

ToolbarItem

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.

En iOS y UWP, el valor de propiedad AutomationProperties.Name reemplazará el valor de propiedad Text que el lector de pantalla lee.

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á. Tenga en cuenta que se trata de una limitación de API inferior a 26.