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. Może też zawierać opcjonalny tytuł, link i przyciski.

Powierzchnia interfejsu API

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

• positionProvider: określa położenie etykietki względem treści elementu zakotwiczonego. Zwykle używasz domyślnego dostawcy pozycji z TooltipDefaults, ale możesz też 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ą:

Wyświetlanie rozbudowanej etykietki

Użyj rozbudowanej etykietki, aby podać dodatkowy kontekst dotyczący elementu interfejsu. W tym przykładzie tworzymy wielowierszową etykietkę z elementami formatowania z tytułem, który jest zakotwiczony 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 detektory zdarzeń dotyczące interakcji użytkownika i odpowiednio aktualizujeTooltipState. Gdy TooltipState wskazuje, że ma się wyświetlić etykietka, wykonywana jest lambda etykietki, a TooltipBox wyświetla 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 działanie klikalne. Gdy naciśniesz i przytrzymasz (na urządzeniach dotykowych) lub najedziesz wskaźnikiem myszy na dowolne miejsce w treści TooltipBox, wyświetli 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:

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ą odrzucenia.
• Po aktywowaniu przez długie naciśnięcie lub najechanie wskaźnikiem myszy na TooltipBox treść 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, 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:

Dodatkowe materiały

• Material Design: Tooltips