Etykietka

Użyj opisu narzędzia, aby dodać kontekst do przycisku lub innego elementu interfejsu. Istnieją 2 rodzaje etykiet narzędzia:

• Proste etykiety: opisują elementy lub działania przycisków z ikonami.
• Szczegółowe informacje w tooltipach: zawierają więcej szczegółów, np. opisują wartość funkcji. Może też zawierać opcjonalny tytuł, link i przyciski.

Interfejs API

Aby wdrożyć w aplikacji etykietkę narzędzia, możesz użyć komponentu TooltipBox. Wygląd 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, ale jeśli potrzebujesz niestandardowej logiki pozycjonowania, możesz podać własnego dostawcę.
• tooltip: komponent zawierający treść tooltipa. Zwykle używasz komponentów PlainTooltip lub RichTooltip.
  • Użyj typu PlainTooltip, aby opisać elementy lub działania ikon przycisków.
  • Użyj RichTooltip, aby podać więcej szczegółów, np. opisać wartość funkcji. Rozszerzone etykiety informacyjne mogą zawierać opcjonalny tytuł, link i przyciski.
• state: element stanu zawierający logikę interfejsu użytkownika i stan elementu w przypadku tej informacji.
• content: kompozytowany element, do którego jest zakotwiczona etykietka.

Wyświetlanie zwykłej etykiety

Aby krótko opisać element interfejsu, użyj zwykłej etykiety. Ten fragment kodu wyświetla zwykłą etykietkę na przycisku 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 etykietę z tekstem „Dodaj do ulubionych”.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() zapewnia domyślne pozycjonowanie prostych etykiet narzędzia.
  • tooltip to funkcja lambda, która definiuje zawartość tooltipa za pomocą elementu PlainTooltip.
  • Text(plainTooltipText) wyświetla tekst w etykiecie.
  • tooltipState określa stan etykiety.
• 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 się z tekstem „Dodaj do ulubionych”. W zależności od urządzenia użytkownicy mogą wyświetlić kartę w następujący sposób:
  • Najechanie kursorem na ikonę
  • Przytrzymanie ikony na urządzeniu mobilnym

Wynik

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

Wyświetlanie rozbudowanej etykiety

Użyj rozszerzonego tekstu sytuacyjnego, aby podać dodatkowy kontekst dotyczący elementu interfejsu. W tym przykładzie etykieta pomocy obejmuje wiele wierszy i zawiera tytuł zakotwiczony do elementu 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 należy wyświetlić etykietkę, funkcja lambda etykiety jest wykonywana, a TooltipBox wyświetla RichTooltip. Element TooltipBox działa jako kotwica i kontener zarówno dla treści, jak i opisu.
  • W tym przypadku treść to komponent IconButton, który umożliwia działanie polegające na kliknięciu. Gdy przytrzymasz (na urządzeniach z ekranem dotykowym) lub najedziesz kursorem (jak wskaźnikiem myszy) na dowolne miejsce w treściach TooltipBox, wyświetli się poradnik z dodatkowymi informacjami.
• Komponent RichTooltip definiuje zawartość tooltipa, w tym tytuł i tekst. TooltipDefaults.rememberRichTooltipPositionProvider() zawiera informacje o pozycji w przypadku rozszerzonych etykiet.

Wynik

Ten przykład powoduje wyświetlenie rozbudowanej etykiety z tytułem dołączonym do ikony informacji:

Dostosowywanie rozbudowanej etykiety narzędzia

Ten fragment kodu wyświetla rozbudowaną etykietę z tytułem, działaniami niestandardowymi i niestandardowym nawiasem (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

• RichToolTip wyświetla etykietę z nazwą i opcją zamknięcia.
• Gdy aktywujesz etykietkę przez długie naciśnięcie lub najechanie kursorem myszy na zawartość ToolTipBox, wyświetla się ona przez około sekundę. Możesz zamknąć tę etykietkę, klikając w inne miejsce na ekranie lub używając przycisku zamknięcia.
• Gdy wykona się działanie odrzucenia, system uruchomi coroutine do wywołania funkcjitooltipState.dismiss. W ten sposób możesz sprawdzić, czy wykonanie działania nie jest zablokowane podczas wyświetlania etykiety.
• onClick = coroutineScope.launch { tooltipState.show() } } uruchamia coroutine, aby ręcznie wyświetlić etykietkę za pomocą funkcji tooltipState.show.
• Parametr action umożliwia dodawanie elementów interaktywnych do okienka z informacjami, np. przycisku.
• Parametr caretSize zmienia rozmiar strzałki w opisie narzędzia.

Wynik

Ten przykład powoduje:

Dodatkowe materiały

• Material Design: piktogramy