Etykietka

Używaj etykietek, aby dodawać 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

Aby zaimplementować w aplikacji etykietki, możesz użyć funkcji kompozycyjnej TooltipBox.TooltipBox wyglądem etykietki sterują te główne parametry:

• 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, która zawiera 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: obiekt stanu, który zawiera logikę interfejsu i stan elementu tego dymku.
• 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ą wyświetlać etykietkę 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 rozbudowanego dymku, 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 elemencie 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 aktualizuje TooltipState. Gdy TooltipState wskazuje, że etykietka ma się wyświetlić, wykonywana jest lambda etykietki, a TooltipBox wyświetla RichTooltip. Element TooltipBox pełni funkcję elementu zakotwiczenia i kontenera zarówno treści, jak i etykietki.
  • W tym przypadku treść jest komponentem IconButton, który zapewnia działanie klikalne. Gdy przytrzymasz (na urządzeniach dotykowych) lub najedziesz kursorem 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() podaje informacje o położeniu rozbudowanych etykietek.

Wynik

Ten przykład tworzy rozbudowaną etykietkę 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)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                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 opcją zamknięcia.
• Po aktywowaniu przez długie naciśnięcie lub najechanie wskaźnikiem myszy na ToolTipBox treści etykietka jest wyświetlana przez około sekundę. Możesz zamknąć ten dymek, klikając w dowolnym miejscu na ekranie lub używając przycisku zamykania.
• Gdy działanie odrzucania zostanie wykonane, system uruchomi korutynę, 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 korutynę, 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