API-Standardeinstellungen

Material, Compose UI und Foundation APIs implementieren und bieten standardmäßig viele barrierefreie Praktiken. Sie enthalten eine integrierte Semantik, die ihrer spezifischen Rolle und Funktion entspricht. Das bedeutet, dass die meisten Bedienungshilfen mit wenig oder gar keinem zusätzlichen Aufwand bereitgestellt werden.

Wenn Sie die richtigen APIs für den richtigen Zweck verwenden, haben Komponenten in der Regel vordefinierte Verhaltensweisen für die Barrierefreiheit, die Standardanwendungsfälle abdecken. Prüfen Sie jedoch immer, ob diese Standardeinstellungen Ihren Anforderungen an die Barrierefreiheit entsprechen. Falls nicht, bietet Compose Möglichkeiten, spezifischere Anforderungen zu erfüllen.

Wenn Sie die standardmäßigen Semantiken und Muster für die Barrierefreiheit in Compose APIs kennen, können Sie sie unter Berücksichtigung der Barrierefreiheit verwenden. Außerdem können Sie so die Barrierefreiheit in mehr benutzerdefinierten Komponenten unterstützen.

Mindestgrößen für Berührungszielbereiche

Bildschirmelemente, die angeklickt bzw. angetippt oder auf sonstige Weise verwendet werden können, müssen ausreichend groß sein, um eine zuverlässige Interaktion zu ermöglichen. Achten Sie beim Festlegen der Größe dieser Elemente darauf, die Mindestgröße auf 48 dp festzulegen, um die Material Design-Richtlinien für Bedienungshilfen einzuhalten.

Material-Komponenten wie Checkbox, RadioButton, Switch, Slider und Surface legen diese Mindestgröße intern fest, aber nur, wenn die Komponente Nutzeraktionen empfangen kann. Wenn beispielsweise der Parameter onCheckedChange eines Checkbox auf einen Wert ungleich null gesetzt ist, wird das Kästchen mit einem Padding versehen, sodass es eine Breite und Höhe von mindestens 48 dp hat.

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

Ein Kästchen mit dem Standard-Padding mit einer Breite und Höhe von 48 dp.
Abbildung 1. Ein Kästchen mit Standard-Padding.

Wenn der Parameter onCheckedChange auf „null“ gesetzt ist, wird das Padding nicht berücksichtigt, da mit der Komponente nicht direkt interagiert werden kann.

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

Ein Kästchen ohne Abstand.
Abbildung 2: Ein Kästchen ohne Abstand.

Wenn Sie Auswahlsteuerelemente wie Switch, RadioButton oder Checkbox implementieren, übertragen Sie das klickbare Verhalten in der Regel auf einen übergeordneten Container. Dazu legen Sie den Klick-Callback für die zusammensetzbare Funktion auf null fest und fügen der übergeordneten zusammensetzbaren Funktion einen toggleable- oder selectable-Modifikator hinzu.

@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)
        }
    }
}

Ein Kästchen neben dem Text „Option“, das ausgewählt und wieder abgewählt wird.
Abbildung 3: Ein Kästchen, das angeklickt werden kann.

Wenn die Größe einer anklickbaren zusammensetzbaren Funktion kleiner als die Mindestgröße des Berührungszielbereichs ist, erhöht Compose die Größe des Berührungszielbereichs trotzdem. Dazu wird die Größe des Berührungszielbereichs über die Grenzen des Composables hinaus erweitert.

Das folgende Beispiel enthält ein sehr kleines anklickbares Box. Der Berührungszielbereich wird automatisch über die Grenzen des Box hinaus erweitert, sodass das Tippen neben dem Box weiterhin das Click-Event auslöst.

@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)
        )
    }
}

Ein sehr kleines anklickbares Feld, das durch Tippen neben dem Feld zu einem größeren Berührungszielbereich erweitert wird.
Abbildung 4: Ein sehr kleines anklickbares Feld, das zu einem größeren Berührungszielbereich erweitert wird.

Um eine mögliche Überschneidung zwischen den Berührungsbereichen verschiedener Composables zu vermeiden, sollten Sie immer eine ausreichend große Mindestgröße für das Composable verwenden. Im Beispiel würde das bedeuten, dass der Modifikator sizeIn verwendet wird, um die Mindestgröße für die innere Box festzulegen:

@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)
        )
    }
}

Das sehr kleine Feld aus dem vorherigen Beispiel wird vergrößert, um einen größeren Berührungszielbereich zu schaffen.
Abbildung 5. Ein größeres Berührungszielbereich-Kästchen.

Wenn das Element eine kleinere sichtbare Größe behalten muss, verwenden Sie stattdessen den Modifikator minimumInteractiveComponentSize aus Material 3. Es reserviert mindestens 48 dp Layoutplatz in jeder Dimension und zentriert das Element in diesem Bereich. So behält das Element seine gezeichnete Größe und die Elemente um es herum werden verschoben, um Platz zu schaffen. Der Modifikator erweitert nicht den Berührungszielbereich selbst, sondern lässt im Layout Platz für die zuvor beschriebene Erweiterung. Materialkomponenten wie Checkbox verwenden diesen Modifikator intern. Platzieren Sie ihn vor allen Größenmodifikatoren, da ein Größenmodifikator davor den Platz einschränkt, den er reservieren kann.

@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")
    }
}

Grafische Elemente

Wenn Sie ein Compose-Element vom Typ Image oder Icon definieren, kann das Android-Framework nicht automatisch erkennen, was die App anzeigt. Sie müssen eine Textbeschreibung des grafischen Elements übergeben.

Stellen Sie sich einen Bildschirm vor, auf dem der Nutzer die aktuelle Seite mit Freunden teilen kann. Dieser Bildschirm enthält ein anklickbares Freigabesymbol:

Eine Leiste mit vier anklickbaren Symbolen, wobei das Symbol „Teilen“ hervorgehoben ist.
Abbildung 6: Eine Reihe anklickbarer Symbole, wobei das Symbol „Teilen“ ausgewählt ist.

Allein anhand des Symbols kann das Android-Framework es einem sehbehinderten Nutzer nicht beschreiben. Das Android-Framework benötigt eine zusätzliche Textbeschreibung des Symbols.

Der Parameter contentDescription beschreibt ein grafisches Element. Verwenden Sie einen lokalisierten String, da er für den Nutzer sichtbar ist.

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

Einige grafische Elemente sind rein dekorativ und müssen dem Nutzer möglicherweise nicht mitgeteilt werden. Wenn Sie den Parameter contentDescription auf null setzen, teilen Sie dem Android-Framework mit, dass diesem Element keine Aktionen oder Status zugeordnet sind.

@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 ist hauptsächlich für grafische Elemente wie Bilder gedacht. Material-Komponenten wie Button oder Text und umsetzbare Verhaltensweisen wie clickable oder toggleable haben andere vordefinierte Semantiken, die ihr intrinsisches Verhalten beschreiben und über andere Compose APIs geändert werden können.

Interaktive Elemente

Die Material- und Foundation Compose APIs erstellen UI-Elemente, mit denen Nutzer über die Modifier APIs clickable und toggleable interagieren können. Da interaktive Komponenten aus mehreren Elementen bestehen können, werden die Semantiken der untergeordneten Elemente von clickable und toggleable standardmäßig zusammengeführt, sodass die Komponente als eine logische Entität behandelt wird.

Ein Material-Button kann beispielsweise aus einem untergeordneten Symbol und etwas Text bestehen. Anstatt die untergeordneten Elemente als einzelne Elemente zu behandeln, führt ein Material-Button die Semantik seiner untergeordneten Elemente standardmäßig zusammen, sodass Bedienungshilfen sie entsprechend gruppieren können:

Schaltflächen mit nicht zusammengeführter und zusammengeführter Semantik für untergeordnete Elemente.
Abbildung 7. Schaltflächen mit nicht zusammengeführter und zusammengeführter Semantik für untergeordnete Elemente.

Wenn Sie den Modifikator clickable verwenden, werden die Semantiken der untergeordneten Elemente einer zusammensetzbaren Funktion ebenfalls in einer einzigen Entität zusammengeführt, die mit einer entsprechenden Aktionsdarstellung an Bedienungshilfen gesendet wird:

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

Du kannst auch ein bestimmtes onClickLabel für das übergeordnete klickbare Element festlegen, um Bedienungshilfen zusätzliche Informationen bereitzustellen und die Aktion besser darzustellen:

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

Am Beispiel von TalkBack würden dieser clickable-Modifikator und sein Klicklabel es TalkBack ermöglichen, einen Aktionshinweis wie „Doppeltippen, um diesen Artikel zu öffnen“ anstelle des allgemeineren Standardfeedbacks „Doppeltippen, um zu aktivieren“ bereitzustellen.

Dieses Feedback ändert sich je nach Art der Aktion. Bei einem langen Klick wird ein TalkBack-Hinweis ausgegeben, der mit „Doppeltippen und halten, um“ beginnt, gefolgt von einem Label:

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

In einigen Fällen hast du möglicherweise keinen direkten Zugriff auf den Modifikator clickable (z. B. wenn er irgendwo in einer niedrigeren verschachtelten Ebene festgelegt ist), möchtest aber trotzdem das Standardlabel für die Ansage ändern. Dazu trennen Sie die Einstellung von clickable von der Änderung der Ankündigung, indem Sie den Modifikator semantics verwenden und dort das Klicklabel festlegen, um die Aktionsdarstellung zu ändern:

@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
                }
            )
        }
    )
}

Sie müssen die Klickaktion nicht zweimal übergeben. Vorhandene Compose APIs wie clickable oder Button übernehmen das für Sie. Die Zusammenführungslogik prüft, ob das äußerste Modifikatorlabel und die äußerste Aktion für die vorhandenen Informationen verwendet werden. Im vorherigen Beispiel übergibt die NestedArticleListItem die Klickaktion openArticle() automatisch an ihre clickable-Semantik. Sie können die Klickaktion in der zweiten Semantikmodifikator-Aktion leer lassen. Das Klicklabel wird jedoch aus dem zweiten Semantikmodifikator onClick(label = "Open this document") übernommen, da es im ersten nicht vorhanden war.

Es kann vorkommen, dass du erwartest, dass die Semantik von untergeordneten Elementen mit der eines übergeordneten Elements zusammengeführt wird, dies aber nicht geschieht. Weitere Informationen finden Sie unter Zusammenführen und löschen.

Benutzerdefinierte Komponenten

Wenn Sie eine benutzerdefinierte Komponente erstellen, sehen Sie sich die Implementierung einer ähnlichen Komponente in der Material-Bibliothek oder anderen Compose-Bibliotheken an. Anschließend können Sie das Verhalten der Bedienungshilfen nach Bedarf nachahmen oder ändern. Wenn Sie beispielsweise das Material-Checkbox durch Ihre eigene Implementierung ersetzen, werden Sie durch die vorhandene Checkbox-Implementierung daran erinnert, den Modifikator triStateToggleable hinzuzufügen, der die Eigenschaften für Bedienungshilfen für die Komponente verarbeitet. Verwenden Sie außerdem häufig Foundation-Modifikatoren, da diese integrierte Überlegungen zur Barrierefreiheit und vorhandene Compose-Verfahren enthalten, die in diesem Abschnitt behandelt werden.

Ein Beispiel für eine benutzerdefinierte Ein/Aus-Komponente finden Sie im Abschnitt „Semantik löschen und festlegen“. Weitere Informationen zur Unterstützung der Barrierefreiheit in benutzerdefinierten Komponenten finden Sie in den API-Richtlinien.