Zmiana kolejności przechodzenia

Kolejność przechodzenia między elementami to kolejność, w jakiej usługi ułatwień dostępu poruszają się po elementach interfejsu. W aplikacji Compose elementy są rozmieszczone w oczekiwanej kolejności czytania, która zwykle jest od lewej do prawej, a następnie z góry na dół. Może się jednak zdarzyć, że Compose będzie potrzebować dodatkowych wskazówek, aby określić prawidłową kolejność odczytu.

isTraversalGroup i traversalIndex to właściwości semantyczne, które pozwalają wpływać na kolejność przechodzenia między elementami w usługach ułatwień dostępu w sytuacjach, gdy domyślny algorytm sortowania Compose nie jest wystarczający. isTraversalGroup identyfikuje ważne semantycznie grupy, które wymagają dostosowania, a traversalIndex dostosowuje kolejność poszczególnych elementów w tych grupach. Możesz użyć samego elementu isTraversalGroup, aby wskazać, że wszystkie elementy w grupie powinny być wybierane razem, lub z elementem traversalIndex, aby uzyskać dalsze możliwości dostosowywania.

Użyj isTraversalGroup i traversalIndex w aplikacji, aby kontrolować kolejność przechodzenia między elementami w czytniku ekranu.

Grupowanie elementów na potrzeby nawigacji

isTraversalGroup to właściwość logiczna, która określa, czy węzeł semantics jest grupą przechodzenia. Ten typ węzła służy jako granica podczas organizowania węzłów podrzędnych.

Ustawienie isTraversalGroup = true w węźle oznacza, że wszystkie elementy podrzędne tego węzła są odwiedzane przed przejściem do innych elementów. Atrybut isTraversalGroup możesz ustawić w przypadku węzłów, które nie są przeznaczone do odczytywania przez czytnik ekranu, takich jak kolumny, wiersze czy pola.

W przykładzie poniżej użyto identyfikatora isTraversalGroup. Emituje 4 elementy tekstowe. Dwa elementy po lewej stronie należą do jednego elementu CardBox, a dwa elementy po prawej stronie należą do innego elementu CardBox:

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

Kod generuje dane wyjściowe podobne do tych:

Ponieważ nie ustawiono semantyki, domyślnym działaniem czytnika ekranu jest przechodzenie przez elementy od lewej do prawej i od góry do dołu. Z powodu tego domyślnego ustawienia TalkBack odczytuje fragmenty zdania w niewłaściwej kolejności:

„To zdanie znajduje się” → „To zdanie to” → „lewa kolumna”. → „po prawej”.

Aby prawidłowo uporządkować fragmenty, zmodyfikuj oryginalny fragment kodu, ustawiając wartość isTraversalGroup na true:

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

Ponieważ właściwość isTraversalGroup jest ustawiana osobno dla każdego elementu CardBox, granice elementu CardBox są stosowane podczas sortowania jego elementów. W tym przypadku najpierw odczytywana jest lewa strona CardBox, a następnie prawa CardBox.

Teraz TalkBack odczytuje fragmenty zdania we właściwej kolejności:

„To zdanie znajduje się” → „w lewej kolumnie”. → „To zdanie to” → „po prawej”.

Dostosowywanie kolejności przechodzenia między elementami

traversalIndex to właściwość zmiennoprzecinkowa, która umożliwia dostosowanie kolejności przechodzenia między elementami w TalkBack. Jeśli grupowanie elementów nie wystarczy, aby funkcja TalkBack działała prawidłowo, użyj traversalIndex w połączeniu z isTraversalGroup, aby dodatkowo dostosować kolejność odczytywania przez czytnik ekranu.

Właściwość traversalIndex ma te cechy:

• Elementy o niższych wartościach traversalIndex mają wyższy priorytet.
• Może być dodatnia lub ujemna.
• Wartością domyślną jest 0f.
• Aby indeks przechodzenia wpływał na zachowanie przechodzenia, musi być ustawiony na komponencie, który będzie można wybrać i na którym usługi ułatwień dostępu będą mogły ustawić ostrość, np. na elementach ekranowych, takich jak tekst lub przyciski.
  • Ustawienie tylko traversalIndex na przykład w Column nie będzie miało żadnego efektu, chyba że w kolumnie ustawiono również isTraversalGroup.

Poniższy przykład pokazuje, jak można używać razem traversalIndex i isTraversalGroup.

Tarcza zegara to typowy przykład, w którym standardowa kolejność przechodzenia między elementami nie działa. Przykładem w tej sekcji jest selektor czasu, w którym użytkownik może przechodzić przez liczby na tarczy zegara i wybierać cyfry dla godzin i minut.

W poniższym uproszczonym fragmencie kodu znajduje się element CircularLayout, w którym narysowano 12 liczb, zaczynając od 12 i idąc zgodnie z ruchem wskazówek zegara:

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

Tarcza zegara nie jest odczytywana logicznie w domyślnej kolejności od lewej do prawej i od góry do dołu, dlatego TalkBack odczytuje liczby w niewłaściwej kolejności. Aby to naprawić, użyj wartości licznika przyrostowego, jak pokazano w tym fragmencie kodu:

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

Aby prawidłowo ustawić kolejność przechodzenia między elementami, najpierw ustaw CircularLayout jako grupę przechodzenia i ustaw isTraversalGroup = true. Następnie, gdy każdy tekst zegara jest rysowany na układzie, ustaw odpowiedni element traversalIndex na wartość licznika.

Wartość licznika stale rośnie, więc wartość traversalIndex każdego zegara jest większa, gdy na ekranie pojawiają się kolejne liczby – wartość zegara 0 ma traversalIndex 0, a wartość zegara 1 ma traversalIndex 1. W ten sposób ustawisz kolejność, w jakiej TalkBack będzie je odczytywać. Teraz liczby wewnątrz CircularLayout są odczytywane w oczekiwanej kolejności.

Ponieważ ustawione wartości traversalIndexes są względne tylko w stosunku do innych indeksów w tej samej grupie, pozostała część kolejności ekranów została zachowana. Innymi słowy, zmiany semantyczne pokazane w poprzednim fragmencie kodu modyfikują tylko kolejność na tarczy zegara, która ma ustawioną wartość isTraversalGroup = true.

Pamiętaj, że nawet jeśli nie ustawisz semantyki CircularLayout's na isTraversalGroup = true, zmiany traversalIndex nadal będą obowiązywać. Jednak bez elementu CircularLayout, który by je wiązał, 12 cyfr tarczy zegara jest odczytywanych na końcu, po wszystkich innych elementach na ekranie. Dzieje się tak, ponieważ wszystkie inne elementy mają domyślną wartość traversalIndex równą 0f, a elementy tekstowe zegara są odczytywane po wszystkich innych elementach 0f.

Uwagi dotyczące interfejsu API

Podczas korzystania z interfejsów API do przechodzenia weź pod uwagę te kwestie:

• Atrybut isTraversalGroup = true powinien być ustawiony w elemencie nadrzędnym zawierającym elementy zgrupowane.
• Właściwość traversalIndex powinna być ustawiona w komponencie podrzędnym, który zawiera semantykę i będzie wybierany przez usługi ułatwień dostępu.
• Upewnij się, że wszystkie elementy, które badasz, są na tym samym poziomie zIndex, ponieważ wpływa to również na semantykę i kolejność przechodzenia między elementami.
• Upewnij się, że żadne semantyki nie są niepotrzebnie scalane, ponieważ może to mieć wpływ na to, do których komponentów są stosowane indeksy przechodzenia.