Interfejsy API Material, Compose UI i Foundation domyślnie implementują i oferują wiele praktyk związanych z ułatwieniami dostępu. Zawierają wbudowaną semantykę, która odpowiada ich konkretnej roli i funkcji. Oznacza to, że większość ułatwień dostępu jest dostępna bez dodatkowej pracy.
Używanie odpowiednich interfejsów API do odpowiednich celów oznacza, że komponenty zwykle mają wstępnie zdefiniowane zachowania ułatwień dostępu, które obejmują standardowe przypadki użycia. Zawsze jednak sprawdzaj, czy te ustawienia domyślne odpowiadają Twoim potrzebom w zakresie ułatwień dostępu. Jeśli nie, Compose oferuje sposoby na spełnienie bardziej szczegółowych wymagań.
Zrozumienie domyślnej semantyki i wzorców ułatwień dostępu w interfejsach API Compose pomaga używać ich z myślą o ułatwieniach dostępu. Pomaga też zapewnić ułatwienia dostępu w większej liczbie komponentów niestandardowych.
Minimalne rozmiary docelowych elementów dotykowych
Każdy element na ekranie, który można kliknąć, dotknąć lub w inny sposób aktywować, musi być na tyle duży, by umożliwiać niezawodną interakcję. Podczas określania rozmiaru tych elementów ustaw minimalny rozmiar na 48 dp, aby zachować zgodność z wytycznymi dotyczącymi ułatwień dostępu w interfejsie Material Design.
Komponenty Material Design, takie jak Checkbox, RadioButton, Switch, Slider i Surface, ustawiają ten minimalny rozmiar wewnętrznie, ale tylko wtedy, gdy komponent może odbierać działania użytkownika. Na przykład gdy parametr onCheckedChange elementu Checkbox ma wartość inną niż null, pole wyboru zawiera dopełnienie, dzięki czemu jego szerokość i wysokość wynoszą co najmniej 48 dp.
@Composable private fun CheckableCheckbox() { Checkbox(checked = true, onCheckedChange = {}) }
Gdy parametr onCheckedChange ma wartość null, dopełnienie nie jest uwzględniane, ponieważ nie można bezpośrednio wejść w interakcję z komponentem.
@Composable private fun NonClickableCheckbox() { Checkbox(checked = true, onCheckedChange = null) }
Podczas implementowania elementów sterujących wyborem, takich jak Switch, RadioButton lub Checkbox, zwykle przenosisz zachowanie kliknięcia do kontenera nadrzędnego, ustawiając wywołanie zwrotne kliknięcia w funkcji kompozycyjnej na null i dodając modyfikator toggleable lub selectable do nadrzędnej funkcji kompozycyjnej.
@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) } } }
Gdy rozmiar klikalnej funkcji kompozycyjnej jest mniejszy niż minimalny rozmiar docelowego elementu dotykowego, Compose i tak zwiększa rozmiar docelowego elementu dotykowego. W tym celu powiększa rozmiar docelowego elementu dotykowego poza granice funkcji kompozycyjnej.
W poniższym przykładzie znajduje się bardzo mały klikalny element Box. Obszar docelowego elementu dotykowego jest automatycznie rozszerzany poza granice elementu Box, więc kliknięcie obok elementu Box nadal wywołuje zdarzenie kliknięcia.
@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) ) } }
Aby zapobiec nakładaniu się obszarów dotykowych różnych funkcji kompozycyjnych, zawsze używaj wystarczająco dużego minimalnego rozmiaru funkcji kompozycyjnej. W tym przykładzie oznacza to użycie modyfikatora sizeIn do ustawienia minimalnego rozmiaru wewnętrznego pola:
@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) ) } }
Jeśli element musi zachować mniejszy rozmiar widoczny, użyj modyfikatora minimumInteractiveComponentSize z Material 3. Rezerwuje co najmniej 48 dp przestrzeni układu w każdym wymiarze i wyśrodkowuje element w tej przestrzeni, dzięki czemu element zachowuje swój rozmiar, a elementy wokół niego przesuwają się, aby zrobić miejsce. Modyfikator nie rozszerza samego docelowego elementu dotykowego, ale pozostawia w układzie miejsce na opisane wcześniej rozszerzenie.
Komponenty Material, takie jak Checkbox, używają tego modyfikatora wewnętrznie. Umieść go przed modyfikatorem rozmiaru, ponieważ modyfikator rozmiaru przed nim ogranicza miejsce, które może zarezerwować.
@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") } }
Elementy graficzne
Gdy definiujesz element kompozycyjny Image lub Icon, platforma Android nie może automatycznie rozpoznać, co wyświetla aplikacja. Musisz przekazać tekstowy opis elementu graficznego.
Wyobraź sobie ekran, na którym użytkownik może udostępnić bieżącą stronę znajomym. Na tym ekranie znajduje się klikalna ikona udostępniania:
Na podstawie samej ikony platforma Androida nie może opisać jej osobie z wadą wzroku. Platforma Androida wymaga dodatkowego opisu tekstowego ikony.
Parametr contentDescription opisuje element graficzny. Użyj zlokalizowanego ciągu znaków, ponieważ jest on widoczny dla użytkownika.
@Composable private fun ShareButton(onClick: () -> Unit) { IconButton(onClick = onClick) { Icon( imageVector = Icons.Filled.Share, contentDescription = stringResource(R.string.label_share) ) } }
Niektóre elementy graficzne mają charakter czysto dekoracyjny i nie trzeba ich przekazywać użytkownikowi. Gdy ustawisz parametr contentDescription na null, poinformujesz platformę Androida, że ten element nie ma powiązanych działań ani stanu.
@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 jest przeznaczony głównie do elementów graficznych, takich jak obrazy. Komponenty Material, takie jak Button lub Text, oraz zachowania, które można wywołać, takie jak clickable lub toggleable, mają inne wstępnie zdefiniowane semantyki, które opisują ich wewnętrzne zachowanie i mogą być zmieniane za pomocą innych interfejsów API Compose.
Elementy interaktywne
Interfejsy API Material i Foundation Compose tworzą elementy interfejsu, z którymi użytkownicy mogą wchodzić w interakcje za pomocą interfejsów API modyfikatorów clickable i toggleable. Komponenty interaktywne mogą składać się z wielu elementów, dlatego clickable i toggleable domyślnie scalają semantykę elementów podrzędnych, aby komponent był traktowany jako jedna jednostka logiczna.
Na przykład element Material Button może składać się z ikony podrzędnej i tekstu. Zamiast traktować elementy podrzędne jako osobne, Material Button domyślnie scala ich semantykę, dzięki czemu usługi ułatwień dostępu mogą je odpowiednio grupować:
Podobnie użycie modyfikatora clickable powoduje, że element kompozycyjny scala semantykę elementów podrzędnych w jedną encję, która jest wysyłana do usług ułatwień dostępu z odpowiednią reprezentacją działania:
Row( // Uses `mergeDescendants = true` under the hood modifier = Modifier.clickable { openArticle() } ) { Icon( painter = painterResource(R.drawable.ic_logo), contentDescription = "Open", ) Text("Accessibility in Compose") }
Możesz też ustawić konkretny onClickLabel w elemencie nadrzędnym, aby przekazać dodatkowe informacje usługom ułatwień dostępu i zapewnić bardziej dopracowaną reprezentację działania:
Row( modifier = Modifier .clickable(onClickLabel = "Open this article") { openArticle() } ) { Icon( painter = painterResource(R.drawable.ic_logo), contentDescription = "Open" ) Text("Accessibility in Compose") }
Na przykładzie TalkBack: ten modyfikator clickable i jego etykieta kliknięcia umożliwiłyby TalkBack wyświetlenie wskazówki dotyczącej działania „Kliknij dwukrotnie, aby otworzyć ten artykuł” zamiast bardziej ogólnej domyślnej informacji zwrotnej „Kliknij dwukrotnie, aby aktywować”.
Te informacje zwrotne zmieniają się w zależności od typu działania. Długie kliknięcie spowoduje, że TalkBack wyświetli wskazówkę „Kliknij dwukrotnie i przytrzymaj, aby”, a następnie etykietę:
Row( modifier = Modifier .combinedClickable( onLongClickLabel = "Bookmark this article", onLongClick = { addToBookmarks() }, onClickLabel = "Open this article", onClick = { openArticle() }, ) ) {}
W niektórych przypadkach możesz nie mieć bezpośredniego dostępu do modyfikatora clickable (np. gdy jest on ustawiony w niższej warstwie zagnieżdżonej), ale nadal chcesz zmienić etykietę powiadomienia z domyślnej. Aby to zrobić, rozdziel ustawianie clickable od modyfikowania ogłoszenia, używając modyfikatora semantics i ustawiając w nim etykietę kliknięcia, aby zmodyfikować reprezentację działania:
@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 } ) } ) }
Nie musisz przekazywać działania kliknięcia dwukrotnie. Istniejące interfejsy API Compose, takie jak clickable lub Button, obsługują to za Ciebie. Logika scalania sprawdza, czy w przypadku obecnych informacji są używane najbardziej zewnętrzne etykieta i działanie modyfikatora. W poprzednim przykładzie NestedArticleListItem automatycznie przekazuje działanie kliknięcia openArticle() do semantyki clickable. W drugim działaniu modyfikatora semantyki możesz pozostawić działanie kliknięcia jako null. Etykieta kliknięcia jest jednak pobierana z drugiego modyfikatora semantyki onClick(label = "Open this document"), ponieważ nie było jej w pierwszym.
Możesz napotkać sytuacje, w których oczekujesz, że semantyka elementów podrzędnych zostanie scalona z semantyką elementu nadrzędnego, ale tak się nie stanie. Więcej informacji znajdziesz w sekcji Scalanie i czyszczenie.
Komponenty niestandardowe
Podczas tworzenia komponentu niestandardowego sprawdź implementację podobnego komponentu w bibliotece Material lub innych bibliotekach Compose. Następnie odpowiednio naśladuj lub zmodyfikuj jego działanie pod kątem ułatwień dostępu. Jeśli na przykład zastąpisz komponent Material Checkbox własną implementacją, spojrzenie na istniejącą implementację Checkbox przypomni Ci o dodaniu modyfikatora triStateToggleable, który obsługuje właściwości ułatwień dostępu komponentu. Dodatkowo intensywnie korzystaj z modyfikatorów Foundation, ponieważ uwzględniają one wbudowane ułatwienia dostępu i istniejące praktyki Compose opisane w tej sekcji.
Przykład niestandardowego komponentu przełącznika znajdziesz też w sekcji dotyczącej czyszczenia i ustawiania semantyki. Bardziej szczegółowe informacje o obsłudze ułatwień dostępu w komponentach niestandardowych znajdziesz w wytycznych dotyczących interfejsu API.
Polecane dla Ciebie
- Uwaga: tekst linku jest wyświetlany, gdy język JavaScript jest wyłączony.
- Ułatwienia dostępu w Compose
- Testowanie układu Compose