Valori predefiniti dell'API

Le API Material, Compose UI e Foundation implementano e offrono molte pratiche accessibili per impostazione predefinita. Contengono una semantica integrata che segue il loro ruolo e la loro funzione specifici. Ciò significa che la maggior parte del supporto per l'accessibilità viene fornita con un lavoro aggiuntivo minimo o nullo.

L'utilizzo delle API appropriate per lo scopo appropriato significa che i componenti di solito sono dotati di comportamenti di accessibilità predefiniti che coprono i casi d'uso standard. Tuttavia, verifica sempre se queste impostazioni predefinite soddisfano le tue esigenze di accessibilità. In caso contrario, Compose offre modi per soddisfare requisiti più specifici.

Comprendere la semantica e i pattern di accessibilità predefiniti nelle API Compose ti aiuta a utilizzarli tenendo conto dell'accessibilità. Inoltre, ti aiuta a supportare l'accessibilità in più componenti personalizzati.

Dimensioni minime dei touch target

Ogni elemento sullo schermo che è possibile selezionare, toccare o con cui è possibile interagire deve essere abbastanza grande da consentire un'opportuna interazione. Quando ridimensioni questi elementi, assicurati di impostare la dimensione minima su 48 dp per seguire correttamente le linee guida sull'accessibilità di Material Design.

I componenti Material, come Checkbox, RadioButton, Switch, Slider e Surface, impostano internamente questa dimensione minima, ma solo quando il componente può ricevere azioni dell'utente. Ad esempio, quando un Checkbox ha il parametro onCheckedChange impostato su un valore non nullo, la casella di controllo include il padding per avere una larghezza e un'altezza di almeno 48 dp.

@Composable
private fun CheckableCheckbox() {
    Checkbox(checked = true, onCheckedChange = {})
}

Una casella di controllo con il padding predefinito con una larghezza e un'altezza di 48 dp.
Figura 1. Una casella di controllo con spaziatura interna predefinita.

Quando il parametro onCheckedChange è impostato su null, il padding non viene incluso perché non è possibile interagire direttamente con il componente.

@Composable
private fun NonClickableCheckbox() {
    Checkbox(checked = true, onCheckedChange = null)
}

Una casella di controllo senza spaziatura interna.
Figura 2. Una casella di controllo senza spaziatura interna.

Quando implementi controlli di selezione come Switch, RadioButton o Checkbox, in genere trasferisci il comportamento cliccabile a un contenitore principale impostando il callback del clic sul composable su null e aggiungendo un modificatore toggleable o selectable al composable principale.

@Composable
private fun CheckableRow() {
    MaterialTheme {
        var checked by remember { mutableStateOf(false) }
        Row(
            Modifier
                .toggleable(
                    value = checked,
                    role = Role.Checkbox,
                    onValueChange = { checked = !checked }
                )
                .padding(16.dp)
                .fillMaxWidth()
        ) {
            Text("Option", Modifier.weight(1f))
            Checkbox(checked = checked, onCheckedChange = null)
        }
    }
}

Una casella di controllo accanto al testo "Opzione" che viene selezionata e deselezionata.
Figura 3. Una casella di controllo con comportamento cliccabile.

Quando le dimensioni di un componibile cliccabile sono inferiori alle dimensioni minime del touch target, Compose aumenta comunque le dimensioni del touch target. A questo scopo, espande le dimensioni del touch target al di fuori dei confini del componibile.

L'esempio seguente contiene un Box cliccabile molto piccolo. L'area del touch target viene espansa automaticamente oltre i confini di Box, quindi il tocco accanto a Box attiva comunque l'evento di clic.

@Composable
private fun SmallBox() {
    var clicked by remember { mutableStateOf(false) }
    Box(
        Modifier
            .size(100.dp)
            .background(if (clicked) Color.DarkGray else Color.LightGray)
    ) {
        Box(
            Modifier
                .align(Alignment.Center)
                .clickable { clicked = !clicked }
                .background(Color.Black)
                .size(1.dp)
        )
    }
}

Una casella cliccabile molto piccola che viene espansa in un touch target più grande toccando accanto alla casella.
Figura 4. Una casella cliccabile molto piccola che viene espansa in un touch target più grande.

Per evitare possibili sovrapposizioni tra le aree di tocco di diversi componibili, utilizza sempre una dimensione minima sufficientemente grande per il componibile. Nell'esempio, ciò significa utilizzare il modificatore sizeIn per impostare la dimensione minima della casella interna:

@Composable
private fun LargeBox() {
    var clicked by remember { mutableStateOf(false) }
    Box(
        Modifier
            .size(100.dp)
            .background(if (clicked) Color.DarkGray else Color.LightGray)
    ) {
        Box(
            Modifier
                .align(Alignment.Center)
                .clickable { clicked = !clicked }
                .background(Color.Black)
                .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
        )
    }
}

La casella molto piccola dell'esempio precedente viene ingrandita per creare un touch target più grande.
Figura 5. Un touch target più grande.

Se l'elemento deve mantenere una dimensione visibile più piccola, utilizza invece il modificatore minimumInteractiveComponentSize di Material 3. Riserva almeno 48 dp di spazio di layout in ogni dimensione e centra l'elemento in quello spazio, in modo che l'elemento mantenga le dimensioni disegnate e gli elementi circostanti si spostino per fare spazio. Il modificatore non espande il touch target, ma lascia spazio nel layout per l'espansione descritta in precedenza. I componenti Material come Checkbox utilizzano questo modificatore internamente. Inseriscilo prima di qualsiasi modificatore di dimensione, perché un modificatore di dimensione prima limita lo spazio che può prenotare.

@Composable
private fun MinimumInteractiveBox() {
    var clicked by remember { mutableStateOf(false) }
    Row(verticalAlignment = Alignment.CenterVertically) {
        Box(
            Modifier
                .clickable { clicked = !clicked }
                .minimumInteractiveComponentSize()
                .size(24.dp)
                .background(if (clicked) Color.DarkGray else Color.Black)
        )
        Text("Option")
    }
}

Elementi grafici

Quando definisci un composable Image o Icon, il framework Android non ha un modo automatico per capire cosa sta visualizzando l'app. Devi passare una descrizione testuale dell'elemento grafico.

Immagina una schermata in cui l'utente può condividere la pagina corrente con gli amici. Questa schermata contiene un'icona di condivisione cliccabile:

Una striscia di quattro icone cliccabili, con l'icona "Condividi" evidenziata.
Figura 6. Una riga di icone cliccabili con l'icona "Condividi" selezionata.

Basandosi solo sull'icona, il framework Android non può descriverla a un utente con disabilità visiva. Il framework Android richiede una descrizione testuale aggiuntiva dell'icona.

Il parametro contentDescription descrive un elemento grafico. Utilizza una stringa localizzata, poiché è visibile all'utente.

@Composable
private fun ShareButton(onClick: () -> Unit) {
    IconButton(onClick = onClick) {
        Icon(
            imageVector = Icons.Filled.Share,
            contentDescription = stringResource(R.string.label_share)
        )
    }
}

Alcuni elementi grafici sono puramente decorativi e potresti non volerli comunicare all'utente. Quando imposti il parametro contentDescription su null, indichi al framework Android che questo elemento non ha azioni o stati associati.

@Composable
private fun PostImage(post: Post, modifier: Modifier = Modifier) {
    val image = post.imageThumb ?: painterResource(R.drawable.placeholder_1_1)

    Image(
        painter = image,
        // Specify that this image has no semantic meaning
        contentDescription = null,
        modifier = modifier
            .size(40.dp, 40.dp)
            .clip(MaterialTheme.shapes.small)
    )
}

contentDescription è destinato principalmente agli elementi grafici, come le immagini. I componenti di Material, come Button o Text, e i comportamenti interattivi, come clickable o toggleable, sono dotati di altre semantiche predefinite che descrivono il loro comportamento intrinseco e possono essere modificati tramite altre API Compose.

Elementi interattivi

Le API Material e Foundation Compose creano elementi UI con cui gli utenti possono interagire tramite le API di modifica clickable e toggleable. Poiché i componenti interattivi possono essere costituiti da più elementi, clickable e toggleable uniscono la semantica dei relativi elementi secondari per impostazione predefinita, in modo che il componente venga trattato come un'unica entità logica.

Ad esempio, un elemento Material Button potrebbe essere costituito da un'icona secondaria e da un testo. Anziché trattare gli elementi secondari come singoli, un Button di Material unisce la semantica degli elementi secondari per impostazione predefinita, in modo che i servizi di accessibilità possano raggrupparli di conseguenza:

Pulsanti con semantica degli elementi secondari non uniti e uniti.
Figura 7. Pulsanti con semantica degli elementi secondari non unita e unita.

Analogamente, l'utilizzo del modificatore clickable fa sì che un composable unisca la semantica dei suoi discendenti in un'unica entità, che viene inviata ai servizi di accessibilità con una rappresentazione dell'azione corrispondente:

Row(
    // Uses `mergeDescendants = true` under the hood
    modifier = Modifier.clickable { openArticle() }
) {
    Icon(
        painter = painterResource(R.drawable.ic_logo),
        contentDescription = "Open",
    )
    Text("Accessibility in Compose")
}

Puoi anche impostare un onClickLabel specifico sull'elemento cliccabile principale per fornire informazioni aggiuntive ai servizi di accessibilità e offrire una rappresentazione più precisa dell'azione:

Row(
    modifier = Modifier
        .clickable(onClickLabel = "Open this article") {
            openArticle()
        }
) {
    Icon(
        painter = painterResource(R.drawable.ic_logo),
        contentDescription = "Open"
    )
    Text("Accessibility in Compose")
}

Utilizzando TalkBack come esempio, questo modificatore clickable e la relativa etichetta di clic consentirebbero a TalkBack di fornire un suggerimento di azione "Tocca due volte per aprire questo articolo", anziché il feedback predefinito più generico "Tocca due volte per attivare".

Questo feedback cambia a seconda del tipo di azione. Un clic lungo fornisce un suggerimento di TalkBack "Tocca due volte e tieni premuto per", seguito da un'etichetta:

Row(
    modifier = Modifier
        .combinedClickable(
            onLongClickLabel = "Bookmark this article",
            onLongClick = { addToBookmarks() },
            onClickLabel = "Open this article",
            onClick = { openArticle() },
        )
) {}

In alcuni casi, potresti non avere accesso diretto al modificatore clickable (ad esempio, quando è impostato in un livello nidificato inferiore),ma vuoi comunque modificare l'etichetta dell'annuncio rispetto a quella predefinita. Per farlo, separa l'impostazione di clickable dalla modifica dell'annuncio utilizzando il modificatore semantics e impostando l'etichetta di clic per modificare la rappresentazione dell'azione:

@Composable
private fun ArticleList(openArticle: () -> Unit) {
    NestedArticleListItem(
        // Clickable is set separately, in a nested layer:
        onClickAction = openArticle,
        // Semantics are set here:
        modifier = Modifier.semantics {
            onClick(
                label = "Open this article",
                action = {
                    // Not needed here: openArticle()
                    true
                }
            )
        }
    )
}

Non è necessario passare l'azione di clic due volte. Le API Compose esistenti, come clickable o Button, gestiscono questa operazione per te. La logica di unione verifica che l'etichetta e l'azione del modificatore più esterno vengano applicate alle informazioni presenti. Nell'esempio precedente, NestedArticleListItem passa automaticamente l'azione di clic openArticle() alla semantica clickable. Puoi lasciare l'azione di clic null nella seconda azione del modificatore di semantica. Tuttavia, l'etichetta del clic viene presa dal secondo modificatore di semantica onClick(label = "Open this document") perché non era presente nel primo.

Potresti riscontrare scenari in cui ti aspetti che la semantica secondaria venga unita a quella principale, ma ciò non accade. Per informazioni più approfondite, consulta Unione e cancellazione.

Componenti personalizzati

Quando crei un componente personalizzato, esamina l'implementazione di un componente simile nella libreria Material o in altre librerie Compose. Poi, imita o modifica il suo comportamento di accessibilità, a seconda dei casi. Ad esempio, se sostituisci Checkbox di Material con la tua implementazione, l'analisi dell'implementazione di Checkbox esistente ti ricorderà di aggiungere il modificatore triStateToggleable, che gestisce le proprietà di accessibilità del componente. Inoltre, utilizza ampiamente i modificatori di Foundation, in quanto includono considerazioni sull'accessibilità integrate e pratiche di Compose esistenti trattate in questa sezione.

Puoi anche trovare un esempio di componente di attivazione/disattivazione personalizzato nella sezione Cancella e imposta la semantica, nonché informazioni più dettagliate su come supportare l'accessibilità nei componenti personalizzati nelle linee guida dell'API.