Etykietka

Użyj etykietek, aby dodać kontekst do przycisku lub innego elementu interfejsu. Istnieją 2 rodzaje etykietek:

• Zwykłe etykietki: opisują elementy lub działania przycisków z ikonami.
• Rozbudowane etykietki: zawierają więcej szczegółów, np. opisują wartość funkcji. Mogą też zawierać opcjonalny tytuł, link i przyciski.

Powierzchnia API

Aby zaimplementować etykietki w aplikacji, możesz użyć elementu kompozycyjnego TooltipBox. Wygląd elementu TooltipBox możesz kontrolować za pomocą tych głównych parametrów:

• positionProvider: umieszcza etykietkę względem treści kotwicy. Zwykle używasz domyślnego dostawcy pozycji z TooltipDefaults lub możesz podać własnego, jeśli potrzebujesz niestandardowej logiki pozycjonowania.
• tooltip: element kompozycyjny, który zawiera treść etykietki. Zwykle używasz elementów kompozycyjnych PlainTooltip lub RichTooltip.
  • Użyj PlainTooltip, aby opisać elementy lub działania przycisków z ikonami.
  • Użyj RichTooltip, aby podać więcej szczegółów, np. opisać wartość funkcji. Rozbudowane etykietki mogą zawierać opcjonalny tytuł, link i przyciski.
• state: kontener stanu, który zawiera logikę interfejsu i stan elementu dla tej etykietki.
• content: element kompozycyjny, do którego jest przymocowana etykietka.

Wyświetlanie zwykłej etykietki

Użyj zwykłej etykietki, aby krótko opisać element interfejsu. Ten fragment kodu wyświetla zwykłą etykietkę nad przyciskiem z ikoną o nazwie „Dodaj do ulubionych”:

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

Najważniejsze informacje o kodzie

• TooltipBox generuje etykietkę z tekstem „Dodaj do ulubionych”.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() zapewnia domyślne pozycjonowanie zwykłych etykietek.
  • tooltip to funkcja lambda, która definiuje treść etykietki za pomocą elementu kompozycyjnego PlainTooltip.
  • Text(plainTooltipText) wyświetla tekst w etykiecie.
  • tooltipState kontroluje stan etykietki.
• IconButton tworzy klikalny przycisk z ikoną.
  • Icon(...) wyświetla ikonę serca w przycisku.
  • Gdy użytkownik wejdzie w interakcję z IconButton, TooltipBox wyświetli etykietkę z tekstem „Dodaj do ulubionych”. W zależności od urządzenia użytkownicy mogą wywołać etykietkę na te sposoby:
  • Najedź kursorem na ikonę.
  • Przytrzymaj ikonę na urządzeniu mobilnym.

Wynik

Ten przykład tworzy zwykłą etykietkę nad ikoną:

Wyświetlanie rozbudowanej etykietki

Użyj rozbudowanej etykietki, aby podać dodatkowy kontekst dotyczący elementu interfejsu. Ten przykład tworzy wielowierszową rozbudowaną etykietkę z tytułem, która jest przymocowana do Icon:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Najważniejsze informacje o kodzie

• TooltipBox obsługuje detektory zdarzeń interakcji użytkownika i odpowiednio aktualizuje TooltipState. Gdy TooltipState wskazuje, że etykietka powinna być wyświetlana, wykonywana jest lambda etykietki, a TooltipBox wyświetla RichTooltip. TooltipBox działa jako kotwica i kontener zarówno treści, jak i etykietki.
  • W tym przypadku treść to komponent IconButton, który zapewnia zachowanie kliknięcia. Gdy przytrzymasz (na urządzeniach dotykowych) lub najedziesz wskaźnikiem myszy (na komputerze) w dowolnym miejscu treści TooltipBox, wyświetli się etykietka z dodatkowymi informacjami.
• Element kompozycyjny RichTooltip definiuje treść etykietki, w tym tytuł i tekst. TooltipDefaults.rememberRichTooltipPositionProvider() zawiera informacje o pozycjonowaniu rozbudowanych etykietek.

Wynik

Ten przykład tworzy rozbudowaną etykietkę z tytułem przymocowanym do ikony informacji:

Dostosowywanie rozbudowanej etykietki

Ten fragment kodu wyświetla rozbudowaną etykietkę z tytułem, niestandardowymi działaniami i niestandardowym karetką (strzałką) wyświetlaną nad przyciskiem z ikoną aparatu:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Najważniejsze informacje o kodzie

• RichTooltip wyświetla etykietkę z tytułem i działaniem odrzucenia.
• Po aktywowaniu przez długie naciśnięcie lub najechaniu wskaźnikiem myszy na treść TooltipBox etykietka jest wyświetlana przez około sekundę. Możesz zamknąć tę etykietkę, klikając w innym miejscu ekranu lub używając przycisku odrzucenia.
• Gdy działanie odrzucenia zostanie wykonane, system uruchomi współprogram, aby wywołać tooltipState.dismiss. Dzięki temu działanie nie jest blokowane, gdy wyświetlana jest etykietka.
• onClick = coroutineScope.launch { tooltipState.show() } } uruchamia współprogram, aby ręcznie wyświetlić etykietkę za pomocą tooltipState.show.
• Parametr action umożliwia dodawanie do etykietki elementów interaktywnych, takich jak przycisk.
• Parametr caretSize modyfikuje rozmiar strzałki etykietki.

Wynik

Ten przykład tworzy:

Dodatkowe materiały

• Material Design: etykietki