Zusammenführen und Bereinigen

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

Wenn Bedienungshilfen Elemente auf dem Bildschirm durchsuchen, ist es wichtig, dass diese Elemente in der richtigen Detailebene gruppiert, getrennt oder sogar ausgeblendet werden. Wenn jedes einzelne Low-Level-Komposit auf dem Bildschirm unabhängig hervorgehoben wird, müssen Nutzer viel interagieren, um sich über den Bildschirm zu bewegen. Wenn Elemente zu stark zusammengeführt werden, können Nutzer möglicherweise nicht nachvollziehen, welche Elemente logisch zusammengehören. Wenn sich auf dem Bildschirm rein dekorative Elemente befinden, können diese für Bedienungshilfen ausgeblendet werden. In diesen Fällen können Sie Compose APIs zum Zusammenführen, Löschen und Ausblenden von Semantik verwenden.

Merge-Semantik

Wenn Sie einen clickable-Modifikator auf ein übergeordnetes Composeable anwenden, werden in Compose automatisch alle untergeordneten Elemente darunter zusammengeführt. Informationen dazu, wie für interaktive Compose-Material- und Foundation-Komponenten standardmäßig Zusammenführungsstrategien verwendet werden, finden Sie im Abschnitt Interaktive Elemente.

Eine Komponente besteht häufig aus mehreren Composeables. Diese Komponenten könnten eine logische Gruppe bilden und jede könnte wichtige Informationen enthalten. Sie möchten jedoch, dass Dienste zur Barrierefreiheit sie als ein Element betrachten.

Stellen Sie sich beispielsweise ein Composeable vor, das den Avatar, den Namen und einige zusätzliche Informationen eines Nutzers enthält:

Sie können Compose so konfigurieren, dass diese Elemente zusammengeführt werden. Verwenden Sie dazu den Parameter mergeDescendants im Semantics-Modifikator. So behandeln Dienste für Barrierefreiheit die Komponente als eine Entität und alle semantischen Eigenschaften der Nachkommen werden zusammengeführt:

@Composable
private fun PostMetadata(metadata: Metadata) {
    // Merge elements below for accessibility purposes
    Row(modifier = Modifier.semantics(mergeDescendants = true) {}) {
        Image(
            imageVector = Icons.Filled.AccountCircle,
            contentDescription = null // decorative
        )
        Column {
            Text(metadata.author.name)
            Text("${metadata.date} • ${metadata.readTimeMinutes} min read")
        }
    }
}
AccessibilitySnippets.kt

Bedienungshilfen-Dienste konzentrieren sich jetzt auf den gesamten Container und verschmelzen seinen Inhalt:

Für jede semantische Property gibt es eine definierte Zusammenführungsstrategie. Mit der Eigenschaft ContentDescription werden beispielsweise alle untergeordneten ContentDescription-Werte in eine Liste aufgenommen. Die Zusammenführungsstrategie einer Semantics-Property kannst du in SemanticsProperties.kt in der mergePolicy-Implementierung prüfen. Untergeordnete oder übergeordnete Werte können übernommen, die Werte in eine Liste oder einen String zusammengeführt, die Zusammenführung überhaupt nicht zugelassen oder stattdessen eine Ausnahme ausgelöst werden. Es ist auch möglich, eine benutzerdefinierte Zusammenführungsstrategie zu verwenden.

Es gibt auch andere Szenarien, in denen Sie davon ausgehen, dass die Semantik von untergeordneten Elementen in eine übergeordnete Element-Semantik zusammengeführt wird, was aber nicht der Fall ist. Im folgenden Beispiel haben wir ein übergeordnetes clickable-Listenelement mit untergeordneten Elementen. Wir gehen davon aus, dass das übergeordnete Element alle zusammenführt:

@Composable
private fun ArticleListItem(
    openArticle: () -> Unit,
    addToBookmarks: () -> Unit,
) {

    Row(modifier = Modifier.clickable { openArticle() }) {
        // Merges with parent clickable:
        Icon(
            painter = painterResource(R.drawable.ic_logo),
            contentDescription = "Article thumbnail"
        )
        ArticleDetails()

        // Defies the merge due to its own clickable:
        BookmarkButton(onClick = addToBookmarks)
    }
}
AccessibilitySnippets.kt

Wenn der Nutzer auf das Element clickable Row drückt, wird der Artikel geöffnet. Darin ist ein BookmarkButton eingebettet, mit dem Sie den Artikel als Lesezeichen speichern können. Diese verschachtelte Schaltfläche wird als nicht zusammengeführt angezeigt, während der Rest der untergeordneten Inhalte in der Zeile zusammengeführt wird:

Einige Elemente werden nicht automatisch mit einem übergeordneten Element zusammengeführt. Ein übergeordnetes Element kann seine untergeordneten Elemente nicht zusammenführen, wenn diese ebenfalls zusammengeführt werden, entweder durch explizites Festlegen von mergeDescendants = true oder durch Komponenten, die sich selbst zusammenführen, z. B. Schaltflächen oder anklickbare Elemente. Wenn Sie wissen, wie bestimmte APIs zusammengeführt werden oder nicht, können Sie einige potenziell unerwartete Verhaltensweisen beheben.

Verwenden Sie das Zusammenführen, wenn untergeordnete Elemente eine logische und sinnvolle Gruppe unter ihrem übergeordneten Element bilden. Wenn die verschachtelten untergeordneten Elemente jedoch manuell angepasst oder ihre eigene Semantik entfernt werden müssen, eignen sich andere APIs möglicherweise besser für Ihre Anforderungen (z. B. clearAndSetSemantics).

Semantik löschen und festlegen

Wenn semantische Informationen vollständig gelöscht oder überschrieben werden müssen, ist die clearAndSetSemantics eine leistungsstarke API.

Wenn die Semantik einer Komponente und ihrer untergeordneten Elemente gelöscht werden muss, verwenden Sie diese API mit einem leeren Lambda. Wenn die Semantik überschrieben werden muss, fügen Sie den neuen Inhalt in das Lambda ein.

Wenn Sie mit einem leeren Lambda löschen, werden die gelöschten Semantiken nicht an Verbraucher gesendet, die diese Informationen verwenden, z. B. für Barrierefreiheit, Autofill oder Tests. Wenn Sie Inhalte mit clearAndSetSemantics{/*semantic information*/} überschreiben, werden alle vorherigen Semantiken des Elements und seiner Nachkommen durch die neue Semantik ersetzt.

Im Folgenden sehen Sie ein Beispiel für eine benutzerdefinierte Ein-/Aus-Schaltfläche, die durch eine interaktive Zeile mit einem Symbol und Text dargestellt wird:

// Developer might intend this to be a toggleable.
// Using `clearAndSetSemantics`, on the Row, a clickable modifier is applied,
// a custom description is set, and a Role is applied.

@Composable
fun FavoriteToggle() {
    val checked = remember { mutableStateOf(true) }
    Row(
        modifier = Modifier
            .toggleable(
                value = checked.value,
                onValueChange = { checked.value = it }
            )
            .clearAndSetSemantics {
                stateDescription = if (checked.value) "Favorited" else "Not favorited"
                toggleableState = ToggleableState(checked.value)
                role = Role.Switch
            },
    ) {
        Icon(
            imageVector = Icons.Default.Favorite,
            contentDescription = null // not needed here

        )
        Text("Favorite?")
    }
}
AccessibilitySnippets.kt

Obwohl das Symbol und der Text einige semantische Informationen enthalten, geben sie zusammen nicht an, dass diese Komponente einschaltbar ist. Das Zusammenführen ist nicht ausreichend, da Sie zusätzliche Informationen zur Komponente angeben müssen.

Da mit dem Snippet oben eine benutzerdefinierte Schalterkomponente erstellt wird, müssen Sie die Schalterfunktion sowie die Semantik stateDescription, toggleableState und role hinzufügen. So sind der Komponentenstatus und die zugehörige Aktion verfügbar. Beispielsweise sagt TalkBack „Zweimal tippen, um zu wechseln“ anstelle von „Zweimal tippen, um zu aktivieren“.

Wenn Sie die ursprünglichen Semantik löschen und neue, aussagekräftigere festlegen, können Dienste zur Barrierefreiheit jetzt erkennen, dass es sich um eine umschaltbare Komponente handelt, die den Status ändern kann.

Beachten Sie bei der Verwendung von clearAndSetSemantics Folgendes:

• Da Dienste keine Informationen erhalten, wenn diese API festgelegt ist, sollten Sie sie sparsam verwenden.
  • Semantische Informationen können von KI-Agenten und ähnlichen Diensten verwendet werden, um den Bildschirm zu verstehen. Sie sollten daher nur bei Bedarf gelöscht werden.
• Benutzerdefinierte Semantik kann innerhalb des API-Lambdas festgelegt werden.
• Die Reihenfolge der Modifikatoren ist wichtig: Diese API löscht alle Semantiken, die nach der Anwendung dieser API kommen, unabhängig von anderen Zusammenführungsstrategien.

Semantik ausblenden

In einigen Fällen müssen Elemente nicht an Bedienungshilfen gesendet werden. Möglicherweise sind die zusätzlichen Informationen für die Barrierefreiheit redundant oder sie dienen nur dekorativen Zwecken und sind nicht interaktiv. In diesen Fällen können Sie Elemente mit der hideFromAccessibility API ausblenden.

In den folgenden Beispielen sind Komponenten zu sehen, die möglicherweise ausgeblendet werden müssen: ein redundantes Wasserzeichen, das eine Komponente überspannt, und ein Zeichen, das Informationen dekorativ voneinander abgrenzt.

@Composable
fun WatermarkExample(
    watermarkText: String,
    content: @Composable () -> Unit,
) {
    Box {
        WatermarkedContent()
        // Mark the watermark as hidden to accessibility services.
        WatermarkText(
            text = watermarkText,
            color = Color.Gray.copy(alpha = 0.5f),
            modifier = Modifier
                .align(Alignment.BottomEnd)
                .semantics { hideFromAccessibility() }
        )
    }
}

@Composable
fun DecorativeExample() {
    Text(
        modifier =
        Modifier.semantics {
            hideFromAccessibility()
        },
        text = "A dot character that is used to decoratively separate information, like •"
    )
}
AccessibilitySnippets.kt

Wenn Sie hier hideFromAccessibility verwenden, werden das Wasserzeichen und die Dekoration für Dienste zur Barrierefreiheit ausgeblendet, behalten aber ihre Semantik für andere Anwendungsfälle wie Tests bei.

Aufschlüsselung der Anwendungsfälle

Im Folgenden finden Sie eine Zusammenfassung von Anwendungsfällen, anhand derer Sie die vorherigen APIs klar unterscheiden können:

• Wenn Inhalte nicht für die Verwendung durch Dienste zur Barrierefreiheit vorgesehen sind:
  • Verwenden Sie hideFromAccessibility, wenn Inhalte möglicherweise dekorativ oder redundant sind, aber trotzdem getestet werden müssen.
  • Verwenden Sie clearAndSetSemantics{} mit einem leeren Lambda, wenn die Semantik von Eltern- und untergeordneten Elementen für alle Dienste gelöscht werden muss.
  • Verwenden Sie clearAndSetSemantics{/*content*/} mit Inhalt innerhalb des Lambdas, wenn die Semantik einer Komponente manuell festgelegt werden muss.
• In folgenden Fällen sollten Inhalte als eine Entität behandelt werden und alle Informationen zu den untergeordneten Elementen müssen vollständig sein:
  • Verwenden Sie semantische Nachkommen zusammenführen.