Kurzinfo

Mit Tooltips können Sie einer Schaltfläche oder einem anderen UI-Element Kontext hinzufügen. Es gibt zwei Arten von Tooltips:

• Einfache Tooltips: Beschreiben Elemente oder Aktionen von Symbolschaltflächen.
• Umfangreiche Tooltips: Bieten mehr Details, z. B. eine Beschreibung des Werts eines Features. Sie können auch einen optionalen Titel, Link und Schaltflächen enthalten.

API-Oberfläche

Mit der TooltipBox zusammensetzbaren Funktion können Sie Tooltips in Ihrer App implementieren. Das Erscheinungsbild von TooltipBox wird mit diesen Hauptparametern gesteuert:

• positionProvider: Platziert den Tooltip relativ zum Ankerinhalt. In der Regel verwenden Sie einen Standardpositionierungsanbieter aus TooltipDefaults. Sie können aber auch einen eigenen angeben, wenn Sie eine benutzerdefinierte Positionierungslogik benötigen.
• tooltip: Die zusammensetzbare Funktion, die den Inhalt des Tooltips enthält. In der Regel verwenden Sie entweder die zusammensetzbaren Funktionen PlainTooltip oder RichTooltip.
  • Verwenden Sie PlainTooltip, um Elemente oder Aktionen von Symbolschaltflächen zu beschreiben.
  • Verwenden Sie RichTooltip, um weitere Details anzugeben, z. B. eine Beschreibung des Werts eines Features. Umfangreiche Tooltips können einen optionalen Titel, Link und Schaltflächen enthalten.
• state: Der Status-Holder, der die UI-Logik und den Elementstatus für diesen Tooltip enthält.
• content: Der zusammensetzbare Inhalt, an dem der Tooltip verankert ist.

Einfachen Tooltip anzeigen

Verwenden Sie einen einfachen Tooltip, um ein UI-Element kurz zu beschreiben. Dieses Code-Snippet zeigt einen einfachen Tooltip über einer Symbolschaltfläche mit der Bezeichnung „Zu Favoriten hinzufügen“ an:

@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 Informationen zum Code

• TooltipBox generiert einen Tooltip mit dem Text „Zu Favoriten hinzufügen“.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() bietet die Standardpositionierung für einfache Tooltips.
  • tooltip ist eine Lambda-Funktion, die den Inhalt des Tooltips mit der PlainTooltip zusammensetzbaren Funktion definiert.
  • Text(plainTooltipText) zeigt den Text im Tooltip an.
  • tooltipState steuert den Status des Tooltips.
• IconButton erstellt eine anklickbare Schaltfläche mit einem Symbol.
  • Icon(...) zeigt ein Herzsymbol in der Schaltfläche an.
  • Wenn ein Nutzer mit IconButton interagiert, zeigt TooltipBox den Tooltip mit dem Text „Zu Favoriten hinzufügen“ an. Je nach Gerät können Nutzer den Tooltip auf folgende Weise auslösen:
  • Mauszeiger auf das Symbol bewegen
  • Symbol auf einem Mobilgerät lange drücken

Ergebnis

In diesem Beispiel wird ein einfacher Tooltip über einem Symbol erstellt:

Umfangreichen Tooltip anzeigen

Verwenden Sie einen umfangreichen Tooltip, um zusätzlichen Kontext zu einem UI-Element bereitzustellen. In diesem Beispiel wird ein mehrzeiliger umfangreicher Tooltip mit einem Titel erstellt, der an einem 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 Informationen zum Code

• TooltipBox verarbeitet die Event-Listener für Nutzerinteraktionen und aktualisiert TooltipState entsprechend. Wenn TooltipState angibt, dass der Tooltip angezeigt werden soll, wird die Tooltip-Lambda-Funktion ausgeführt und TooltipBox zeigt RichTooltip an. TooltipBox dient als Anker und Container für Inhalt und Tooltip.
  • In diesem Fall ist der Inhalt eine IconButton-Komponente, die das Verhalten für anklickbare Aktionen bietet. Wenn Sie auf einem Touchgerät lange auf eine beliebige Stelle im Inhalt von TooltipBox drücken oder den Mauszeiger darauf bewegen, wird der Tooltip mit weiteren Informationen angezeigt.
• Die zusammensetzbare Funktion RichTooltip definiert den Inhalt des Tooltips, einschließlich Titel und Text. TooltipDefaults.rememberRichTooltipPositionProvider() enthält Informationen zur Positionierung für umfangreiche Tooltips.

Ergebnis

In diesem Beispiel wird ein umfangreicher Tooltip mit einem Titel erstellt, der an ein Informationssymbol angehängt ist:

Umfangreichen Tooltip anpassen

Dieses Code-Snippet zeigt einen umfangreichen Tooltip mit einem Titel, benutzerdefinierten Aktionen und einem benutzerdefinierten Caret (Pfeil) über einer Schaltfläche mit einem Kamerasymbol an:

@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

Wichtige Informationen zum Code

• Ein RichToolTip zeigt einen Tooltip mit einem Titel und einer Aktion zum Schließen an.
• Wenn der Tooltip durch langes Drücken oder Bewegen des Mauszeigers auf den Inhalt von ToolTipBox aktiviert wird, wird er etwa eine Sekunde lang angezeigt. Sie können diesen Tooltip schließen, indem Sie entweder an einer anderen Stelle auf dem Bildschirm tippen oder die Aktionsschaltfläche zum Schließen verwenden.
• Wenn die Aktion zum Schließen ausgeführt wird, startet das System eine Coroutine, um tooltipState.dismiss aufzurufen. Dadurch wird sichergestellt, dass die Ausführung der Aktion nicht blockiert wird, während der Tooltip angezeigt wird.
• onClick = coroutineScope.launch { tooltipState.show() } } startet eine Coroutine, um den Tooltip mit tooltipState.show manuell anzuzeigen.
• Mit dem Parameter action können interaktive Elemente wie eine Schaltfläche zu einem Tooltip hinzugefügt werden.
• Mit dem Parameter caretSize wird die Größe des Pfeils des Tooltips geändert.

Ergebnis

Dieses Beispiel erzeugt Folgendes:

Zusätzliche Ressourcen

• Material Design: Tooltips