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 = {}) }
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) }

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) } } }
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) ) } }
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) ) } }
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:
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:
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.
Empfehlungen für Sie
- Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
- Barrierefreiheit in Compose
- Compose-Layout testen