Proprietà di automazione in Xamarin.Forms

  • Articolo

Xamarin.Forms consente di impostare i valori di accessibilità sugli elementi dell'interfaccia utente usando proprietà associate dalla classe AutomationProperties, che a sua volta impostano i valori di accessibilità nativi. Questo articolo illustra come usare la classe AutomationProperties, in modo che un'utilità per la lettura dello schermo possa annunciare gli elementi della pagina.

Xamarin.Forms consente di impostare le proprietà di automazione sugli elementi dell'interfaccia utente tramite le proprietà associate seguenti:

  • AutomationProperties.IsInAccessibleTree: indica se l'elemento è disponibile per un'applicazione accessibile. Per altre informazioni, vedere AutomationProperties.IsInAccessibleTree.
  • AutomationProperties.Name: una breve descrizione dell'elemento che funge da identificatore pronunciabile per l'elemento. Per altre informazioni, vedere AutomationProperties.Name.
  • AutomationProperties.HelpText: una descrizione più lunga dell'elemento assimilabile al testo della descrizione comando associato all'elemento. Per altre informazioni, vedere AutomationProperties.HelpText.
  • AutomationProperties.LabeledBy: consente a un altro elemento di definire le informazioni di accessibilità per l'elemento corrente. Per altre informazioni, vedere AutomationProperties.LabeledBy.

Queste proprietà associate impostano valori di accessibilità nativi in modo che l'utilità per la lettura dello schermo possa presentare l'elemento. Per altre informazioni sulle proprietà associate, vedere Proprietà associate.

Importante

L'uso delle proprietà associate AutomationProperties può rallentare l'esecuzione del test dell'interfaccia utente in Android. Le proprietà AutomationProperties.Name e AutomationProperties.HelpText di AutomationId imposteranno entrambe la proprietà ContentDescription nativa, in cui i valori AutomationProperties.Name e AutomationProperties.HelpText hanno la precedenza sul valore AutomationId. Se AutomationProperties.Name e AutomationProperties.HelpText sono entrambe impostate, i valori saranno concatenati. Ciò significa che i test che cercano AutomationId avranno esito negativo se anche AutomationProperties.Name o AutomationProperties.HelpText è impostato per l'elemento. In questo scenario, i test dell'interfaccia utente dovrebbero essere modificati per cercare il valore AutomationProperties.Name o AutomationProperties.HelpText, o una concatenazione dei due.

In ogni piattaforma è presente un'utilità per la lettura dello schermo diversa tramite la quale enunciare i valori di accessibilità:

Tuttavia, il comportamento esatto di un'utilità per la lettura dello schermo dipende dal software e dalla relativa configurazione scelta dall'utente. La maggior parte delle utilità per la lettura dello schermo, ad esempio, leggono il testo associato a un controllo quando questo riceve lo stato attivo, consentendo agli utenti di orientarsi mentre si spostano tra i controlli della pagina. Alcune utilità per la lettura dello schermo leggono anche l'intera interfaccia utente dell'applicazione quando viene visualizzata una pagina, così che l'utente conosca tutto il contenuto informativo della pagina prima di iniziare a spostarsi al suo interno.

Inoltre, le utilità per la lettura dello schermo leggono valori di accessibilità diversi. Nell'applicazione di esempio:

  • VoiceOver leggerà il valore Placeholder del controllo Entry, seguito dalle istruzioni per l'uso del controllo.
  • TalkBack leggerà il valore Placeholder del controllo Entry, seguito dal valore AutomationProperties.HelpText, seguito dalle istruzioni per l'uso del controllo.
  • Assistente vocale leggerà il valore AutomationProperties.LabeledBy del controllo Entry, seguito dalle istruzioni per l'uso del controllo.

Inoltre, Assistente vocale classifica in ordine di priorità AutomationProperties.Name, AutomationProperties.LabeledBy e quindi AutomationProperties.HelpText. In Android può accadere che TalkBack combini i valori AutomationProperties.Name e AutomationProperties.HelpText. Pertanto, per garantire un'esperienza ottimale, si consiglia di eseguire test completi sull'accessibilità su ogni piattaforma.

AutomationProperties.IsInAccessibleTree

La proprietà associata AutomationProperties.IsInAccessibleTree è un valore boolean che determina se l'elemento è accessibile, e pertanto visibile, alle utilità per la lettura dello schermo. Per poter usare le altre proprietà associate di accessibilità, deve essere impostata su true. Per ottenere questo risultato, è possibile procedere come segue in XAML:

<Entry AutomationProperties.IsInAccessibleTree="true" />

In alternativa, può essere impostata in C# come indicato di seguito:

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

Nota

Si noti che il metodo SetValue può essere utilizzato anche per impostare la proprietà associata AutomationProperties.IsInAccessibleTree – entry.SetValue(AutomationProperties.IsInAccessibleTreeProperty, true);

AutomationProperties.Name

Il valore della proprietà associata AutomationProperties.Name deve essere una stringa di testo breve e descrittiva che l'utilità per la lettura dello schermo possa usare per annunciare un elemento. Questa proprietà deve essere impostata per gli elementi indispensabili per comprendere il contenuto o l'interazione con l'interfaccia utente. Per ottenere questo risultato, è possibile procedere come segue in XAML:

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

In alternativa, può essere impostata in C# come indicato di seguito:

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

Nota

Si noti che il metodo SetValue può essere utilizzato anche per impostare la proprietà associata AutomationProperties.Name – activityIndicator.SetValue(AutomationProperties.NameProperty, "Progress indicator");

AutomationProperties.HelpText

La proprietà associata AutomationProperties.HelpText deve essere impostata su testo che descriva l'elemento dell'interfaccia utente e assimilabile al testo della descrizione comando associata all'elemento. Per ottenere questo risultato, è possibile procedere come segue in XAML:

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

In alternativa, può essere impostata in C# come indicato di seguito:

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

Nota

Si noti che il metodo SetValue può essere utilizzato anche per impostare la proprietà associata AutomationProperties.HelpText – button.SetValue(AutomationProperties.HelpTextProperty, "Tap to toggle the activity indicator");

In alcune piattaforme, per i controlli di modifica come Entry, la proprietà HelpText può essere talvolta omessa e sostituita con testo segnaposto. Ad esempio, "Inserisci qui il tuo nome" è un buon candidato per la proprietà Entry.Placeholder che inserisce il testo nel controllo prima dell'effettivo input dell'utente.

AutomationProperties.LabeledBy

La proprietà associata AutomationProperties.LabeledBy consente a un altro elemento di definire le informazioni di accessibilità per l'elemento corrente. Ad esempio, un elemento Label accanto a un controllo Entry può essere utilizzato per descrivere che cosa rappresenta Entry. Per ottenere questo risultato, è possibile procedere come segue in XAML:

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

In alternativa, può essere impostata in C# come indicato di seguito:

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

Importante

Non AutomationProperties.LabeledByProperty è ancora supportato in iOS.

Nota

Si noti che il metodo SetValue può essere utilizzato anche per impostare la proprietà associata AutomationProperties.IsInAccessibleTree – entry.SetValue(AutomationProperties.LabeledByProperty, nameLabel);

Aspetti complessi dell'accessibilità

Le sezioni seguenti descrivono aspetti complessi dell'impostazione dei valori di accessibilità su determinati controlli.

In Android, per impostare il testo dello schermo che viene letto per la freccia Indietro nella barra delle azioni in un elemento NavigationPage, impostare le proprietà AutomationProperties.Name e AutomationProperties.HelpText su Page. Tenere tuttavia presente che questo non ha nessun effetto sui pulsanti Indietro del sistema operativo.

FlyoutPage

In iOS e nella piattaforma UWP (Universal Windows Platform), per impostare il testo letto dalle utilità per la lettura dello schermo per l'interruttore in un elemento FlyoutPage, impostare le proprietà AutomationProperties.Name e AutomationProperties.HelpText su FlyoutPage, oppure sulla proprietà IconImageSource della pagina Flyout.

In Android, per impostare il testo che le utilità per la lettura dello schermo leggono per l'interruttore in un elemento FlyoutPage, aggiungere risorse stringa al progetto 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>

Impostare quindi la proprietà AutomationId della proprietà IconImageSource della pagina Flyout sulla stringa appropriata:

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

ToolbarItem

In iOS, Android e nella piattaforma UWP (Universal Windows Platform) le utilità per la lettura dello schermo leggono il valore della proprietà Text delle istanze ToolbarItem, a condizione che i valori AutomationProperties.Name o AutomationProperties.HelpText non siano definiti.

In iOS e nella piattaforma UWP il valore della proprietà AutomationProperties.Name sostituisce il valore della proprietà Text che viene letto dall'utilità per la lettura dello schermo.

In Android i valori delle proprietà AutomationProperties.Name e/o AutomationProperties.HelpText sostituiranno completamente il valore della proprietà Text che è visibile e viene letto dall'utilità per la lettura dello schermo. Si noti che questa è una limitazione per le API inferiori alla 26.