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. opis wartości funkcji. Mogą też zawierać opcjonalny tytuł, link i przyciski.

Rysunek 1. Zwykła etykietka (1) i etykietka z elementami rozszerzonymi (2).

Powierzchnia interfejsu API

Za pomocą komponentu kompozycyjnego TooltipBox możesz zaimplementować w aplikacji etykietki. Wygląd komponentu TooltipBox możesz kontrolować za pomocą tych głównych parametrów:

• positionProvider: umieszcza etykietkę w stosunku do 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: funkcja kompozycyjna zawierająca treść etykietki. Zwykle używasz funkcji kompozycyjnych PlainTooltip lub RichTooltip.
  • Użyj typu 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: zmienna stanu, która zawiera logikę interfejsu i stan elementu tej etykietki.
• content: treść, do której jest przypięty element kompozycyjny.

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ą komponentu PlainTooltip.
  • Text(plainTooltipText) wyświetla tekst w etykietce.
  • tooltipState określa stan etykietki.
• IconButton tworzy klikalny przycisk z ikoną.
  • Icon(...) wyświetla ikonę serca w przycisku.
  • Gdy użytkownik wejdzie w interakcję z elementem IconButton, TooltipBox wyświetli etykietkę z tekstem „Dodaj do ulubionych”. W zależności od urządzenia użytkownicy mogą wywołać wskazówkę na te sposoby:
  • Najedź kursorem na ikonę.
  • przytrzymanie ikony na urządzeniu mobilnym,

Wynik

W tym przykładzie tworzymy zwykłą etykietkę nad ikoną:

Rysunek 2. Prosta etykietka, która pojawia się, gdy użytkownik najedzie kursorem na ikonę serca lub przytrzyma ją.

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 zakotwiczona w 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 odbiorniki zdarzeń interakcji użytkownika i odpowiednio aktualizuje TooltipState. Gdy TooltipState wskaże, że należy wyświetlić etykietkę, zostanie wykonana lambda etykietki, a TooltipBox wyświetli RichTooltip. Element TooltipBox działa jako element zakotwiczenia i kontener zarówno treści, jak i etykietki.
  • W tym przypadku treść jest komponentem IconButton, który zapewnia zachowanie działania po kliknięciu. Gdy naciśniesz i przytrzymasz (na urządzeniach dotykowych) lub najedziesz wskaźnikiem myszy na dowolne miejsce w treści TooltipBox, pojawi się podpowiedź z dodatkowymi informacjami.
• Funkcja RichTooltip określa zawartość etykietki, w tym tytuł i tekst. TooltipDefaults.rememberRichTooltipPositionProvider() – udostępnia informacje o położeniu rozbudowanych podpowiedzi.

Wynik

Ten przykład generuje rozbudowany tooltip z tytułem dołączonym do ikony informacji:

Rysunek 3. Etykietka z tytułem i ikoną informacji.

Dostosowywanie rozbudowanej etykietki

Ten fragment kodu wyświetla rozbudowaną etykietkę z tytułem, niestandardowymi działaniami i niestandardowym znakiem wstawienia (strzałką) wyświetlanym 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

• Ikona RichTooltip wyświetla etykietkę z tytułem i czynnością zamykania.
• Po aktywowaniu przez długie naciśnięcie lub najechanie wskaźnikiem myszy na TooltipBoxtreść etykietka jest wyświetlana przez około sekundę. Aby zamknąć ten dymek, kliknij w dowolnym miejscu na ekranie lub użyj przycisku zamykania.
• Gdy działanie odrzucania zostanie wykonane, system uruchomi współprogram, aby wywołać funkcję tooltipState.dismiss. Sprawdza to, czy wykonanie działania nie jest blokowane podczas wyświetlania etykietki.
• onClick = coroutineScope.launch { tooltipState.show() } } uruchamia współprogram, aby ręcznie wyświetlić etykietkę za pomocą tooltipState.show.
• Parametr action umożliwia dodawanie do etykiet interaktywnych elementów, takich jak przycisk.
• Parametr caretSize modyfikuje rozmiar strzałki etykietki.

Wynik

Ten przykład daje następujący wynik:

Rysunek 4. Niestandardowa rozbudowana etykietka z działaniem zamykania, która jest przytwierdzona do ikony kamery.

Dodatkowe materiały

• Material Design: Tooltips