Durchlaufreihenfolge ändern

Die Durchquerungsreihenfolge ist die Reihenfolge, in der Bedienungshilfen durch UI-Elemente navigieren. In einer Compose-App sind die Elemente in der erwarteten Lesereihenfolge angeordnet, also normalerweise von links nach rechts und dann von oben nach unten. In einigen Fällen benötigt Compose jedoch möglicherweise zusätzliche Hinweise, um die richtige Lesereihenfolge zu bestimmen.

isTraversalGroup und traversalIndex sind semantische Properties, mit denen Sie die Durchlaufreihenfolge für Bedienungshilfen in Szenarien beeinflussen können, in denen der Standardsortieralgorithmus von Compose nicht ausreicht. isTraversalGroup identifiziert semantisch wichtige Gruppen, die angepasst werden müssen, während traversalIndex die Reihenfolge der einzelnen Elemente innerhalb dieser Gruppen anpasst. Sie können isTraversalGroup allein verwenden, um anzugeben, dass alle Elemente innerhalb einer Gruppe zusammen ausgewählt werden sollen, oder mit traversalIndex für weitere Anpassungen.

Verwenden Sie isTraversalGroup und traversalIndex in Ihrer App, um die Screenreader-Durchlaufreihenfolge zu steuern.

Elemente für die Navigation gruppieren

isTraversalGroup ist ein boolesches Attribut, das definiert, ob ein Semantikknoten eine Durchlaufgruppe ist. Dieser Knotentyp dient als Grenze oder Rahmen für die Organisation der untergeordneten Knoten.

Wenn Sie isTraversalGroup = true für einen Knoten festlegen, werden alle untergeordneten Elemente dieses Knotens besucht, bevor andere Elemente aufgerufen werden. Sie können isTraversalGroup für Knoten festlegen, die nicht für Screenreader fokussierbar sind, z. B. Spalten, Zeilen oder Felder.

Im folgenden Beispiel wird isTraversalGroup verwendet. Es werden vier Textelemente ausgegeben. Die beiden linken Elemente gehören zu einem CardBox-Element, während die beiden rechten Elemente zu einem anderen CardBox-Element gehören:

// CardBox() function takes in top and bottom sample text.
@Composable
fun CardBox(
    topSampleText: String,
    bottomSampleText: String,
    modifier: Modifier = Modifier
) {
    Box(modifier) {
        Column {
            Text(topSampleText)
            Text(bottomSampleText)
        }
    }
}

@Composable
fun TraversalGroupDemo() {
    val topSampleText1 = "This sentence is in "
    val bottomSampleText1 = "the left column."
    val topSampleText2 = "This sentence is "
    val bottomSampleText2 = "on the right."
    Row {
        CardBox(
            topSampleText1,
            bottomSampleText1
        )
        CardBox(
            topSampleText2,
            bottomSampleText2
        )
    }
}

Die Ausgabe des Codes sieht in etwa so aus:

Layout mit zwei Textspalten. In der linken Spalte steht „Dieser Satz befindet sich in der linken Spalte“ und in der rechten Spalte „Dieser Satz befindet sich in der rechten Spalte“.
Abbildung 1. Ein Layout mit zwei Sätzen (einer in der linken und einer in der rechten Spalte).

Da keine Semantik festgelegt wurde, ist das Standardverhalten des Screenreaders, Elemente von links nach rechts und von oben nach unten zu durchlaufen. Aufgrund dieser Standardeinstellung liest TalkBack die Satzfragmente in der falschen Reihenfolge vor:

„Dieser Satz steht in“ → „Dieser Satz steht“ → „der linken Spalte.“ → „auf der rechten Seite“.

Wenn Sie die Fragmente richtig anordnen möchten, ändern Sie das ursprüngliche Snippet so, dass isTraversalGroup auf true gesetzt wird:

@Composable
fun TraversalGroupDemo2() {
    val topSampleText1 = "This sentence is in "
    val bottomSampleText1 = "the left column."
    val topSampleText2 = "This sentence is"
    val bottomSampleText2 = "on the right."
    Row {
        CardBox(
//      1,
            topSampleText1,
            bottomSampleText1,
            Modifier.semantics { isTraversalGroup = true }
        )
        CardBox(
//      2,
            topSampleText2,
            bottomSampleText2,
            Modifier.semantics { isTraversalGroup = true }
        )
    }
}

Da isTraversalGroup für jede CardBox spezifisch festgelegt wird, gelten die Grenzen der CardBox beim Sortieren ihrer Elemente. In diesem Fall wird zuerst der linke CardBox und dann der rechte CardBox gelesen.

TalkBack liest die Satzfragmente jetzt in der richtigen Reihenfolge vor:

„Dieser Satz steht“ → „in der linken Spalte.“ → „Der Satz lautet“ → „auf der rechten Seite.“

Durchlaufreihenfolge anpassen

traversalIndex ist eine Gleitkomma-Property, mit der Sie die TalkBack-Durchlaufreihenfolge anpassen können. Wenn das Gruppieren von Elementen nicht ausreicht, damit TalkBack richtig funktioniert, können Sie traversalIndex in Verbindung mit isTraversalGroup verwenden, um die Reihenfolge des Screenreaders weiter anzupassen.

Das Attribut traversalIndex hat die folgenden Eigenschaften:

  • Elemente mit niedrigeren traversalIndex-Werten werden zuerst priorisiert.
  • Kann positiv oder negativ sein.
  • Der Standardwert ist 0f.
  • Damit der Durchlaufindex das Durchlaufverhalten beeinflusst, muss er für eine Komponente festgelegt werden, die von Bedienungshilfen ausgewählt und fokussiert werden kann, z. B. für Bildschirmelemente wie Text oder Schaltflächen.
    • Wenn Sie beispielsweise nur traversalIndex für eine Column festlegen, hat dies keine Auswirkungen, es sei denn, für die Spalte ist auch isTraversalGroup festgelegt.

Das folgende Beispiel zeigt, wie Sie traversalIndex und isTraversalGroup zusammen verwenden können.

Ein Zifferblatt ist ein gängiges Szenario, bei dem die Standard-Durchlaufreihenfolge nicht funktioniert. Das Beispiel in diesem Abschnitt ist eine Zeitauswahl, bei der ein Nutzer die Zahlen auf einem Zifferblatt durchgehen und Ziffern für die Stunden- und Minutenfelder auswählen kann.

Ein Zifferblatt mit einer Zeitauswahl darüber.
Abbildung 2: Bild eines Zifferblatts

Im folgenden vereinfachten Snippet gibt es ein CircularLayout, in dem 12 Zahlen gezeichnet werden, beginnend mit 12 und im Uhrzeigersinn um den Kreis:

@Composable
fun ClockFaceDemo() {
    CircularLayout {
        repeat(12) { hour ->
            ClockText(hour)
        }
    }
}

@Composable
private fun ClockText(value: Int) {
    Box(modifier = Modifier) {
        Text((if (value == 0) 12 else value).toString())
    }
}

Da das Zifferblatt nicht logisch von links nach rechts und von oben nach unten gelesen wird, liest TalkBack die Zahlen in der falschen Reihenfolge vor. Verwenden Sie zur Behebung dieses Problems den inkrementierenden Zählerwert, wie im folgenden Snippet gezeigt:

@Composable
fun ClockFaceDemo() {
    CircularLayout(Modifier.semantics { isTraversalGroup = true }) {
        repeat(12) { hour ->
            ClockText(hour)
        }
    }
}

@Composable
private fun ClockText(value: Int) {
    Box(modifier = Modifier.semantics { this.traversalIndex = value.toFloat() }) {
        Text((if (value == 0) 12 else value).toString())
    }
}

Wenn Sie die Durchlaufreihenfolge richtig festlegen möchten, machen Sie zuerst die CircularLayout zu einer Durchlaufgruppe und legen Sie isTraversalGroup = true fest. Wenn dann der Text für die einzelnen Uhren im Layout gezeichnet wird, setze den entsprechenden traversalIndex auf den Zählerwert.

Da der Zählerwert kontinuierlich steigt, ist der traversalIndex-Wert jedes Uhrwerts größer, wenn Zahlen auf dem Bildschirm hinzugefügt werden. Der Uhrwert 0 hat einen traversalIndex-Wert von 0 und der Uhrwert 1 hat einen traversalIndex-Wert von 1. So wird die Reihenfolge festgelegt, in der TalkBack sie vorliest. Jetzt werden die Zahlen innerhalb des CircularLayout in der erwarteten Reihenfolge gelesen.

Da die festgelegten traversalIndexes nur relativ zu anderen Indexen innerhalb derselben Gruppierung sind, bleibt die restliche Bildschirmreihenfolge erhalten. Die im vorherigen Code-Snippet gezeigten semantischen Änderungen ändern also nur die Reihenfolge innerhalb des Zifferblatts, für das isTraversalGroup = true festgelegt ist.

Beachten Sie, dass die traversalIndex-Änderungen auch dann gelten, wenn die Semantik von CircularLayout's nicht auf isTraversalGroup = true gesetzt ist. Ohne das CircularLayout, um sie zu binden, werden die zwölf Ziffern des Zifferblatts jedoch zuletzt gelesen, nachdem alle anderen Elemente auf dem Bildschirm besucht wurden. Das liegt daran, dass alle anderen Elemente einen Standard-traversalIndex von 0f haben und die Textelemente der Uhr nach allen anderen 0f-Elementen gelesen werden.

Überlegungen zu APIs

Beachten Sie bei der Verwendung der Traversal APIs Folgendes:

  • isTraversalGroup = true sollte für das übergeordnete Element festgelegt werden, das die gruppierten Elemente enthält.
  • traversalIndex sollte für eine untergeordnete Komponente festgelegt werden, die Semantik enthält und von Bedienungshilfen ausgewählt wird.
  • Achten Sie darauf, dass sich alle Elemente, die Sie untersuchen, auf derselben zIndex-Ebene befinden, da sich dies auch auf die Semantik und die Durchlaufreihenfolge auswirkt.
  • Achten Sie darauf, dass keine Semantik unnötig zusammengeführt wird, da sich dies darauf auswirken kann, auf welche Komponenten Durchlaufindexe angewendet werden.