API-Standardeinstellungen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Material, Compose UI und Foundation APIs implementieren und bieten standardmäßig viele barrierefreie Praktiken. Sie enthalten integrierte Semantiken, die ihrer jeweiligen Rolle und Funktion entsprechen. Das bedeutet, dass der Großteil der Unterstützung für Barrierefreiheit mit wenig oder gar keiner zusätzlichen Arbeit bereitgestellt wird.

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

Wenn Sie die Standard-Semantik und -Muster für die Barrierefreiheit in Compose APIs kennen, können Sie sie besser im Hinblick auf die Barrierefreiheit verwenden und 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, sollten 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 Richtlinien für Bedienungshilfen in Material Design einzuhalten.

Bei Materialkomponenten wie Checkbox, RadioButton, Switch, Slider und Surface wird diese Mindestgröße intern festgelegt, aber nur, wenn die Komponente Nutzeraktionen empfangen kann. Wenn beispielsweise der Parameter onCheckedChange eines Checkbox auf einen nicht nullwertigen Wert festgelegt ist, hat das Kästchen einen Mindestabstand von 48 dp in der Breite und Höhe.

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

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

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

Wenn Sie Auswahlsteuerelemente wie Switch, RadioButton oder Checkbox implementieren, übertragen Sie das anklickbare Verhalten in der Regel auf einen übergeordneten Container. Dazu legen Sie den Klick-Callback für das zusammensetzbare Element auf null fest und fügen dem übergeordneten zusammensetzbaren Element 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)
        }
    }
}
AccessibilitySnippets.kt

Wenn die Größe eines anklickbaren Compose-Elements kleiner als die Mindestgröße des Berührungszielbereichs ist, wird die Größe des Berührungszielbereichs in Compose trotzdem erhöht. Dazu wird die Größe des Touch-Ziels über die Grenzen des Composeables hinaus erweitert.

Das folgende Beispiel enthält ein sehr kleines anklickbares Box. Der Touch-Zielbereich wird automatisch über die Grenzen des Box hinaus erweitert. Wenn Sie also neben dem Box tippen, wird das Klickereignis trotzdem ausgelö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)
        )
    }
}
AccessibilitySnippets.kt

Um Überschneidungen zwischen Touchbereichen verschiedener Composeables zu vermeiden, sollten Sie für das Composeable immer eine ausreichend große Mindestgröße verwenden. Im Beispiel würde das bedeuten, dass Sie mit dem Modifikator sizeIn die Mindestgröße für den inneren Frame festlegen:

@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)
        )
    }
}
AccessibilitySnippets.kt

Grafikelemente

Wenn Sie ein Image- oder Icon-Composeable definieren, kann das Android-Framework nicht automatisch erkennen, was in der App angezeigt wird. Sie müssen eine textuelle Beschreibung des Grafikelements angeben.

Stellen Sie sich einen Bildschirm vor, auf dem Nutzer die aktuelle Seite mit Freunden teilen können. Auf diesem Bildschirm befindet sich ein anklickbares Freigabesymbol:

Anhand des Symbols allein 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 Grafikelement. 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)
        )
    }
}
AccessibilitySnippets.kt

Einige grafische Elemente sind rein dekorativ und sollten den Nutzern nicht mitgeteilt werden. Wenn Sie den Parameter contentDescription auf null festlegen, geben Sie dem Android-Framework an, dass für dieses Element keine Aktionen oder Status festgelegt 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)
    )
}
AccessibilitySnippets.kt

contentDescription ist hauptsächlich für grafische Elemente wie Bilder gedacht. Materialkomponenten wie Button oder Text und ausführbare Verhaltensweisen wie clickable oder toggleable haben andere vordefinierte Semantiken, die ihr inhärentes Verhalten beschreiben, und können über andere Compose APIs geändert werden.

Interaktive Elemente

Mit den Material und Foundation Compose APIs können Sie UI-Elemente erstellen, mit denen Nutzer über die Modifizierer-APIs clickable und toggleable interagieren können. Da interaktive Komponenten aus mehreren Elementen bestehen können, werden die Semantiken ihrer 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 Text bestehen. Anstatt die untergeordneten Elemente einzeln zu behandeln, werden sie bei einer Material-Schaltfläche standardmäßig zusammengeführt, damit Bedienungshilfen sie entsprechend gruppieren können:

Wenn Sie den Modifikator clickable verwenden, werden die Semantiken der Nachkommen eines Composeables ebenfalls in einer einzelnen Entität zusammengeführt, die mit einer entsprechenden Aktionsdarstellung an Dienste zur Barrierefreiheit 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")
}
AccessibilitySnippets.kt

Sie können auch eine bestimmte onClickLabel für das übergeordnete anklickbare Element festlegen, um Dienste zur Barrierefreiheit zusätzliche Informationen zur Verfügung zu stellen und eine ansprechendere Darstellung der Aktion zu ermöglichen:

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

Anhand von TalkBack als Beispiel: Mit diesem clickable-Modifikator und seinem Klicklabel könnte TalkBack einen Aktionshinweis wie „Zum Öffnen dieses Artikels doppeltippen“ anzeigen, anstatt der allgemeineren Standardrückmeldung „Zum Aktivieren doppeltippen“.

Dieses Feedback ändert sich je nach Art der Aktion. Bei einem langen Tippen wird die TalkBack-Hinweismeldung „Zweimal tippen und gedrückt halten, um…“ gefolgt von einem Label angezeigt:

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

In einigen Fällen haben Sie möglicherweise keinen direkten Zugriff auf den clickable-Modifikator (z. B. wenn er sich in einer niedriger verschachtelten Ebene befindet), möchten aber trotzdem das Ansagelabel ändern. Dazu trennen Sie die Einstellung der clickable von der Änderung der Ankündigung. Verwenden Sie dazu den Modifikator semantics und legen Sie dort das Klicklabel fest, 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
                }
            )
        }
    )
}
AccessibilitySnippets.kt

In diesem Fall müssen Sie die Klickaktion nicht zweimal übergeben, da vorhandene Compose APIs wie clickable oder Button dies für Sie übernehmen. Das liegt daran, dass die Zusammenführungslogik dafür sorgt, dass das äußerste Modifiziererlabel und die äußerste Aktion für die vorhandenen Informationen verwendet werden.

Im vorherigen Beispiel wird die openArticle()-Klickaktion von der NestedArticleListItem automatisch an die clickable-Semantik übergeben und kann in der zweiten Aktion für den Semantik-Modifikator leer bleiben. Das Klicklabel wird jedoch aus dem zweiten semantischen Modifikator onClick(label = "Open this article") übernommen, da es im ersten nicht vorhanden war.

Es kann vorkommen, dass Sie davon ausgehen, dass untergeordnete Semantik in eine übergeordnete Semantik zusammengeführt wird, dies aber nicht geschieht. Weitere Informationen finden Sie unter Zusammenführen und Löschen.

Benutzerdefinierte Komponenten

Bei benutzerdefinierten Komponenten sollten Sie sich als Faustregel die Implementierung einer ähnlichen Komponente in der Materialbibliothek oder in anderen Compose-Bibliotheken ansehen und das Verhalten der Barrierefreiheit nachahmen oder ändern, wenn dies sinnvoll ist.

Wenn Sie beispielsweise das Material Checkbox durch Ihre eigene Implementierung ersetzen, werden Sie durch die vorhandene Kästchenimplementierung daran erinnert, den Modifikator triStateToggleable hinzuzufügen, der die Barrierefreiheitseigenschaften für diese Komponente verwaltet.

Außerdem sollten Sie die Foundation-Modifikatoren häufig verwenden, da sie standardmäßig Aspekte der Barrierefreiheit sowie bestehende Compose-Praktiken umfassen, die in diesem Abschnitt behandelt werden.

Im Abschnitt Semantik löschen und festlegen finden Sie ein Beispiel für eine benutzerdefinierte Ein-/Aus-Schaltfläche. In den API-Richtlinien finden Sie außerdem ausführlichere Informationen dazu, wie Sie die Barrierefreiheit in benutzerdefinierten Komponenten unterstützen.