Kurzinfo

Verwenden Sie Tooltips, um einer Schaltfläche oder einem anderen UI-Element Kontext hinzuzufügen. Es gibt zwei Arten von Kurzinfos:

• Glasklare Kurzinfos: Hier werden Elemente oder Aktionen von Symbolschaltflächen beschrieben.
• Ausführliche Kurzinfos: Sie können mehr Details angeben, z. B. den Wert einer Funktion. Sie können auch einen optionalen Titel, einen Link und Schaltflächen enthalten.

API-Oberfläche

Mit dem TooltipBox-Komposit können Sie in Ihrer App Kurzinfos implementieren. Mit den folgenden Hauptparametern können Sie das Aussehen von TooltipBox steuern:

• positionProvider: Platziert die Kurzinfo relativ zum Ankerinhalt. Normalerweise wird ein Standardpositionierungsanbieter aus der TooltipDefaults verwendet. Sie können aber auch einen eigenen Anbieter angeben, wenn Sie eine benutzerdefinierte Positionierungslogik benötigen.
• tooltip: Das Element, das den Inhalt der Kurzinfo enthält. Normalerweise verwenden Sie entweder die PlainTooltip- oder die RichTooltip-Kompositionen.
  • Verwenden Sie PlainTooltip, um Elemente oder Aktionen von Symbolschaltflächen zu beschreiben.
  • Verwenden Sie RichTooltip, um weitere Details anzugeben, z. B. den Wert einer Funktion. Ausführliche Kurzinfos können einen optionalen Titel, einen Link und Schaltflächen enthalten.
• state: Der Statushalter, der die UI-Logik und den Elementstatus für diese Kurzinfo enthält.
• content: Der zusammensetzbare Inhalt, an dem die Kurzinfo verankert ist.

Nur eine Kurzinfo anzeigen

Verwenden Sie eine einfache Kurzinfo, um ein UI-Element kurz zu beschreiben. In diesem Code-Snippet wird über einer Symbolschaltfläche eine einfache Kurzinfo mit der Beschriftung „Zu Favoriten hinzufügen“ angezeigt:

@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

Wichtige Punkte zum Code

• TooltipBox generiert eine Kurzinfo mit dem Text „Zu Favoriten hinzufügen“.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() bietet die Standardpositionierung für einfache Kurzinfos.
  • tooltip ist eine Lambda-Funktion, die den Inhalt der Kurzinfo mithilfe des PlainTooltip-Elements definiert.
  • Text(plainTooltipText) zeigt den Text in der Kurzinfo an.
  • Mit tooltipState wird der Status der Kurzinfo gesteuert.
• Mit IconButton wird eine anklickbare Schaltfläche mit einem Symbol erstellt.
  • Bei Icon(...) wird in der Schaltfläche ein Herzsymbol angezeigt.
  • Wenn ein Nutzer mit dem IconButton interagiert, wird in TooltipBox die Kurzinfo mit dem Text „Zu Favoriten hinzufügen“ angezeigt. Je nach Gerät können Nutzer die Kurzinfo auf folgende Weisen aufrufen:
  • Mit dem Mauszeiger auf das Symbol zeigen
  • Auf einem Mobilgerät lange auf das Symbol drücken

Ergebnis

In diesem Beispiel wird eine einfache Kurzinfo über einem Symbol angezeigt:

Eine Rich-Text-Kurzinfo anzeigen

Verwenden Sie eine ausführliche Kurzinfo, um zusätzlichen Kontext zu einem UI-Element bereitzustellen. In diesem Beispiel wird eine mehrzeilige Rich-Tooltip-Funktion mit einem Titel erstellt, der an einer Icon verankert ist:

@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

Wichtige Punkte zum Code

• TooltipBox verarbeitet die Ereignis-Listener für Nutzerinteraktionen und aktualisiert TooltipState entsprechend. Wenn TooltipState angibt, dass die Kurzinfo angezeigt werden soll, wird das Kurzinfo-Lambda ausgeführt und TooltipBox zeigt RichTooltip an. Das TooltipBox dient als Anker und Container sowohl für den Inhalt als auch für die Kurzinfo.
  • In diesem Fall ist der Inhalt eine IconButton-Komponente, die das Verhalten der anklickbaren Aktion definiert. Wenn Sie auf einem Touch-Gerät lange auf einen beliebigen Inhalt von TooltipBox drücken oder den Mauszeiger darauf bewegen, wird eine Kurzinfo mit weiteren Informationen angezeigt.
• Mit dem RichTooltip-Element wird der Inhalt der Kurzinfo definiert, einschließlich Titel und Textkörper. TooltipDefaults.rememberRichTooltipPositionProvider() enthält Informationen zur Positionierung von aussagekräftigen Kurzinfos.

Ergebnis

In diesem Beispiel wird eine umfangreiche Kurzinfo mit einem Titel erstellt, der an ein Informationssymbol angehängt ist:

Rich-Text-Kurzinfo anpassen

In diesem Code-Snippet wird eine umfangreiche Kurzinfo mit einem Titel, benutzerdefinierten Aktionen und einem benutzerdefinierten Caret (Pfeil) über einer Kamerasymbolschaltfläche angezeigt:

@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

Wichtige Punkte zum Code

• Ein RichToolTip zeigt eine Kurzinfo mit einem Titel und einer Aktion zum Schließen an.
• Wenn die Kurzinfo aktiviert wird, entweder durch langes Drücken oder durch Bewegen des Mauszeigers auf den ToolTipBox-Inhalt, wird sie etwa eine Sekunde lang angezeigt. Sie können diese Kurzinfo schließen, indem Sie entweder woanders auf dem Bildschirm tippen oder die Schaltfläche „Schließen“ verwenden.
• Wenn die Aktion „Schließen“ ausgeführt wird, startet das System eine Coroutine, um tooltipState.dismiss aufzurufen. So wird überprüft, ob die Ausführung der Aktion nicht blockiert wird, während die Kurzinfo angezeigt wird.
• onClick = coroutineScope.launch { tooltipState.show() } } startet eine Coroutine, um die Kurzinfo manuell mit tooltipState.show anzuzeigen.
• Mit dem Parameter action können Sie einem Kurzinfo interaktive Elemente hinzufügen, z. B. eine Schaltfläche.
• Mit dem Parameter caretSize wird die Größe des Pfeils in der Kurzinfo geändert.

Ergebnis

In diesem Beispiel wird Folgendes ausgegeben:

Zusätzliche Ressourcen

• Material Design: Tooltips