Etykietka

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

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

Interfejs API

Aby zaimplementować etykietki w aplikacji, możesz użyć funkcji kompozycyjnej 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żywa się domyślnego dostawcy pozycji z TooltipDefaults, ale możesz też podać własnego, jeśli potrzebujesz niestandardowej logiki pozycjonowania.
• tooltip: element kompozycyjny zawierający treść etykietki. Zwykle używa się funkcji kompozycyjnych PlainTooltip lub RichTooltip.
  • Użyj PlainTooltip, aby opisać elementy lub działania przycisków ikon.
  • Użyj RichTooltip, aby podać więcej szczegółów, np. opisać wartość funkcji. Rozszerzone etykietki mogą zawierać opcjonalny tytuł, link i przyciski.
• state: zmienna stanu, która zawiera logikę interfejsu i stan elementu dla tej etykietki.
• content: zawartość funkcji kompozycyjnej, do której jest zakotwiczona 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 ikony z etykietą „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(
                painter = rememberVectorPainter(AppIcons.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 zawartość etykietki za pomocą elementu kompozycyjnego PlainTooltip.
  • Text(plainTooltipText) wyświetla tekst w etykietce.
  • tooltipState określa stan etykietki.
• IconButton tworzy klikalny przycisk z ikoną.
  • Icon(...) wyświetla ikonę serca na 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ć etykietkę na te sposoby:
  • Najedź kursorem na ikonę.
  • przytrzymanie ikony na urządzeniu mobilnym,

Wynik

W tym przykładzie nad ikoną wyświetla się zwykła etykietka:

Wyświetlanie rozszerzonej etykietki

Użyj rozszerzonej etykietki, aby podać dodatkowy kontekst dotyczący elementu interfejsu. W tym przykładzie tworzona jest wielowierszowa sformatowana etykietka 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(
                painter = rememberVectorPainter(AppIcons.Info),
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Najważniejsze informacje o kodzie

• TooltipBox obsługuje detektory zdarzeń dla interakcji użytkownika i odpowiednio aktualizuje TooltipState. Gdy TooltipState wskazuje, że etykietka powinna być wyświetlana, wykonywana jest funkcja lambda etykietki, a TooltipBox wyświetla RichTooltip. Element TooltipBox działa jako kotwica i kontener zarówno dla treści, jak i etykietki.
  • W tym przypadku treścią jest komponent IconButton, który zapewnia działanie po kliknięciu. Gdy przytrzymasz (na urządzeniach dotykowych) lub najedziesz kursorem (np. wskaźnikiem myszy) na dowolne miejsce w treści TooltipBox, wyświetli się etykietka z dodatkowymi informacjami.
• Funkcja kompozycyjna RichTooltip definiuje zawartość etykietki, w tym tytuł i treść. TooltipDefaults.rememberRichTooltipPositionProvider() dostarcza informacje o pozycjonowaniu dla rozszerzonych etykietek.

Wynik

Ten przykład pokazuje, jak utworzyć rozszerzoną etykietkę z tytułem dołączonym do ikony informacji:

Dostosowywanie rozszerzonej etykietki

Ten fragment kodu wyświetla rozszerzoną etykietkę z tytułem, działaniami niestandardowymi i niestandardowym kursorem (strzałką) 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(
                painter = rememberVectorPainter(AppIcons.Camera),
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Najważniejsze informacje o kodzie

• RichTooltip wyświetla etykietkę z tytułem i działaniem odrzucenia.
• Po aktywacji, przez przytrzymanie lub najechanie wskaźnikiem myszy na treść TooltipBox, etykietka jest wyświetlana przez około sekundę. Możesz zamknąć tę etykietkę, klikając w innym miejscu na ekranie lub używając przycisku polecenia zamknięcia.
• Gdy zostanie wykonane działanie odrzucenia, system uruchomi współprogram, aby wywołać funkcję tooltipState.dismiss. Sprawdź, czy wykonanie działania nie jest blokowane, gdy wyświetla się 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 zmienia rozmiar strzałki etykietki.

Wynik

Ten przykład daje taki wynik:

Dodatkowe materiały

• Material Design: etykietki