Gdy usługi ułatwień dostępu poruszają się po elementach na ekranie, ważne jest, aby te elementy były pogrupowane, rozdzielone lub nawet ukryte na odpowiednim poziomie szczegółowości. Gdy każdy element kompozycyjny niskiego poziomu na ekranie jest wyróżniony niezależnie, użytkownicy muszą wykonać wiele działań, aby poruszać się po ekranie. Jeśli elementy łączą się zbyt agresywnie, użytkownicy mogą nie zrozumieć, które elementy logicznie do siebie pasują. Jeśli na ekranie znajdują się elementy, które są czysto dekoracyjne, można je ukryć przed usługami ułatwień dostępu. W takich przypadkach możesz używać interfejsów API Compose do scalania, czyszczenia i ukrywania semantyki.
Scalanie semantyki
Gdy zastosujesz modyfikator clickable do nadrzędnego elementu kompozycyjnego, Compose automatycznie scali wszystkie elementy podrzędne. Aby dowiedzieć się, jak interaktywne komponenty Compose Material i Foundation domyślnie używają strategii scalania, zapoznaj się z sekcją Elementy interaktywne.
Komponent często składa się z kilku funkcji kompozycyjnych. Te elementy kompozycyjne mogą tworzyć grupę logiczną i każdy z nich może zawierać ważne informacje, ale możesz chcieć, aby usługi ułatwień dostępu traktowały je jako jeden element.
Wyobraź sobie na przykład funkcję kompozycyjną, która wyświetla awatar użytkownika, jego imię i nazwisko oraz dodatkowe informacje:
Możesz włączyć w Compose scalanie tych elementów, używając parametru mergeDescendants w modyfikatorze semantyki. Dzięki temu usługi ułatwień dostępu traktują komponent jako jedną encję, a wszystkie właściwości semantyczne elementów podrzędnych są scalane:
@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") } } }
Usługi ułatwień dostępu skupiają się teraz na całym kontenerze naraz i łączą jego zawartość:
Każda właściwość semantyki ma zdefiniowaną strategię scalania. Na przykład właściwość ContentDescription dodaje do listy wszystkie wartości podrzędne ContentDescription. Strategię scalania właściwości semantycznej możesz sprawdzić, analizując jej implementację mergePolicy w pliku SemanticsProperties.kt.
Właściwości mogą przyjmować wartość nadrzędną lub podrzędną, scalać wartości w listę lub ciąg znaków, nie zezwalać na scalanie i zgłaszać wyjątek lub stosować inną niestandardową strategię scalania.
Istnieją inne scenariusze, w których oczekujesz, że semantyka elementów podrzędnych zostanie scalona z semantyką elementu nadrzędnego, ale tak się nie dzieje. W tym przykładzie mamy element nadrzędny elementu listy clickable z elementami podrzędnymi i możemy oczekiwać, że element nadrzędny scali je wszystkie:
@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) } }
Gdy użytkownik kliknie element clickable Row, otworzy się artykuł. Wewnątrz znajduje się element BookmarkButton, który umożliwia dodanie artykułu do zakładek. Ten zagnieżdżony przycisk jest wyświetlany jako nierozdzielony, podczas gdy pozostałe treści podrzędne w wierszu są scalone:
Row. Niescalone drzewo zawiera osobne węzły dla każdego Text elementu kompozycyjnegoNiektóre elementy kompozycyjne nie są automatycznie scalane pod elementem nadrzędnym. Element nadrzędny nie może scalać elementów podrzędnych, gdy te elementy również są scalane, czy to przez wyraźne ustawienie mergeDescendants = true, czy przez bycie komponentami, które same się scalają, takimi jak przyciski lub elementy klikalne. Wiedza o tym, jak niektóre interfejsy API scalają się lub nie, może pomóc w debugowaniu potencjalnie nieoczekiwanych zachowań.
Scalaj elementy, gdy elementy podrzędne tworzą logiczną i sensowną grupę pod elementem nadrzędnym. Jeśli jednak zagnieżdżone elementy podrzędne wymagają ręcznego dostosowania lub usunięcia własnej semantyki, inne interfejsy API mogą lepiej odpowiadać Twoim potrzebom (np. clearAndSetSemantics).
Wyczyść i ustaw semantykę
Jeśli informacje semantyczne muszą zostać całkowicie wyczyszczone lub zastąpione, warto użyć interfejsu API clearAndSetSemantics.
Gdy komponent musi wyczyścić semantykę własną i swoich elementów podrzędnych, użyj tego interfejsu API z pustą funkcją lambda. Jeśli chcesz zastąpić jego semantykę, umieść nową treść w funkcji lambda.
Pamiętaj, że podczas czyszczenia za pomocą pustej funkcji lambda wyczyszczone semantyki nie są wysyłane do żadnego klienta, który korzysta z tych informacji, np. ułatwień dostępu, autouzupełniania czy testowania. Gdy zastępujesz treść za pomocą clearAndSetSemantics{/*semantic information*/}, nowa semantyka zastępuje całą poprzednią semantykę elementu i jego elementów podrzędnych.
Poniżej znajdziesz przykład niestandardowego komponentu przełącznika, który jest reprezentowany przez interaktywny wiersz z ikoną i tekstem:
// 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?") } }
Chociaż ikona i tekst zawierają pewne informacje semantyczne, razem nie wskazują, że ten komponent można przełączać. Scalanie nie wystarczy, ponieważ musisz podać dodatkowe informacje o komponencie.
Powyższy fragment kodu tworzy niestandardowy komponent przełącznika, dlatego musisz dodać możliwość przełączania oraz semantykę stateDescription, toggleableState i role. Dzięki temu stan komponentu i powiązane z nim działanie są dostępne – na przykład TalkBack ogłasza „Kliknij dwukrotnie, aby przełączyć” zamiast „Kliknij dwukrotnie, aby aktywować”.
Dzięki usunięciu pierwotnej semantyki i ustawieniu nowej, bardziej opisowej, usługi ułatwień dostępu mogą teraz rozpoznać, że jest to komponent przełączany, który może zmieniać stan.
Podczas korzystania z clearAndSetSemantics weź pod uwagę te kwestie:
- Ponieważ usługi nie otrzymują żadnych informacji, gdy ten interfejs API jest ustawiony, lepiej używać go oszczędnie.
- Informacje semantyczne mogą być używane przez agentów AI i podobne usługi do zrozumienia ekranu, dlatego powinny być usuwane tylko wtedy, gdy jest to konieczne.
- Niestandardową semantykę można ustawić w funkcji lambda interfejsu API.
- Kolejność modyfikatorów ma znaczenie – ten interfejs API usuwa wszystkie elementy semantyczne, które znajdują się po miejscu, w którym został zastosowany, niezależnie od innych strategii scalania.
Ukryj semantykę
W niektórych przypadkach elementy nie muszą być wysyłane do usług ułatwień dostępu – być może ich dodatkowe informacje są zbędne dla ułatwień dostępu lub są to elementy czysto dekoracyjne i nieinteraktywne. W takich przypadkach możesz ukryć elementy za pomocą interfejsu API hideFromAccessibility.
W poniższych przykładach przedstawiono komponenty, które mogą wymagać ukrycia: zbędny znak wodny, który obejmuje komponent, oraz znak używany do dekoracyjnego oddzielania informacji.
@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 •" ) }
Użycie tutaj hideFromAccessibility zapewnia, że znak wodny i dekoracja są ukryte przed usługami ułatwień dostępu, ale zachowują swoją semantykę w innych przypadkach użycia, takich jak testowanie.
Zestawienie przypadków użycia
Poniżej znajdziesz podsumowanie przypadków użycia, które pomoże Ci zrozumieć, jak wyraźnie odróżnić poprzednie interfejsy API:
- Jeśli treści nie są przeznaczone do użytku przez usługi ułatwień dostępu:
- Użyj
hideFromAccessibility, gdy treść może być dekoracyjna lub zbędna, ale nadal musi zostać przetestowana. - Użyj
clearAndSetSemantics{}z pustą funkcją lambda, gdy trzeba wyczyścić semantykę nadrzędną i podrzędną we wszystkich usługach. - Użyj
clearAndSetSemantics{/*content*/}z treścią wewnątrz funkcji lambda, gdy semantykę komponentu trzeba ustawić ręcznie.
- Użyj
- Gdy treści powinny być traktowane jako jedna encja i wymagają wszystkich informacji o elementach podrzędnych:
- Użyj scalania semantycznych elementów podrzędnych.
Polecane dla Ciebie
- Uwaga: tekst linku jest wyświetlany, gdy język JavaScript jest wyłączony.
- Ułatwienia dostępu w Compose
- [Material Design 2 w Compose][19]
- Testowanie układu Compose