Kurzinfo

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

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

Abbildung 1: Eine einfache Kurzinfo (1) und eine Rich-Tooltip (2).

API-Oberfläche

Mit der TooltipBox-Composable können Sie Tooltips in Ihrer App implementieren. Die Darstellung von TooltipBox wird mit den folgenden Hauptparametern gesteuert:

• positionProvider: Positioniert den Tooltip relativ zum Ankerinhalt. Normalerweise verwenden Sie einen Standardanbieter für die Positionierung aus TooltipDefaults. Sie können aber auch einen eigenen Anbieter angeben, wenn Sie eine benutzerdefinierte Logik für die Positionierung benötigen.
• tooltip: Die zusammensetzbare Funktion, die den Inhalt der Kurzinfo enthält. Normalerweise verwenden Sie entweder die Composables PlainTooltip oder RichTooltip.
  • Verwenden Sie PlainTooltip, um Elemente oder Aktionen von Symbolschaltflächen zu beschreiben.
  • Mit RichTooltip können Sie weitere Details angeben, z. B. den Wert einer Funktion beschreiben. Rich-Kurzinfos 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 das Tooltip verankert ist.

Einfache Kurzinfo anzeigen

Verwenden Sie einen einfachen Kurzinfo-Text, um ein UI-Element kurz zu beschreiben. In diesem Code-Snippet wird eine einfache Kurzinfo über einer Symbolschaltfläche mit dem Label „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 eine Standardpositionierung für einfache Tooltips.
  • tooltip ist eine Lambda-Funktion, die den Inhalt des Tooltips mit der zusammensetzbaren Funktion PlainTooltip 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.
  • Icon(...) zeigt ein Herzsymbol in der Schaltfläche an.
  • Wenn ein Nutzer mit dem IconButton interagiert, wird in TooltipBox der Kurzinfo-Text „Zu Favoriten hinzufügen“ angezeigt. Je nach Gerät können Nutzer den Kurzinfo-Text auf folgende Weise aufrufen:
  • Mit dem Cursor auf das Symbol zeigen
  • Langes Drücken des Symbols auf einem Mobilgerät

Ergebnis

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

Abbildung 2. Eine einfache Kurzinfo, die angezeigt wird, wenn ein Nutzer den Mauszeiger auf das Herzsymbol bewegt oder es lange drückt.

Rich-Kurzinfo anzeigen

Verwenden Sie eine Rich-Kurzinfo, um zusätzlichen Kontext zu einem UI-Element bereitzustellen. In diesem Beispiel wird ein mehrzeiliger Rich-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 Punkte zum Code

• TooltipBox verarbeitet die Event-Listener für Nutzerinteraktionen und aktualisiert TooltipState entsprechend. Wenn TooltipState angibt, dass die Kurzinfo angezeigt werden soll, wird die Lambda-Funktion für die Kurzinfo ausgeführt und TooltipBox zeigt die RichTooltip an. Das TooltipBox-Element dient als Anker und Container für den Inhalt und die Kurzinfo.
  • In diesem Fall ist der Inhalt eine IconButton-Komponente, die das Verhalten für Tippaktionen bereitstellt. Wenn Sie auf Touchgeräten lange auf den Inhalt von TooltipBox tippen oder den Mauszeiger darauf bewegen, wird die Kurzinfo mit weiteren Informationen angezeigt.
• Mit der zusammensetzbaren Funktion RichTooltip wird der Inhalt des Tooltips definiert, einschließlich des Titels und des Textkörpers. TooltipDefaults.rememberRichTooltipPositionProvider() enthält Informationen zur Positionierung von Rich-Kurzinfos.

Ergebnis

In diesem Beispiel wird ein umfangreicher Kurzinfo-Text mit einem Titel generiert, der an ein Informationssymbol angehängt ist:

Abbildung 3. Eine ausführliche Kurzinfo mit einem Titel und einem Infosymbol.

Rich-Kurzinfo anpassen

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

@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

• Bei einem RichToolTip wird eine Kurzinfo mit einem Titel und einer Schließen-Aktion angezeigt.
• Wenn die Kurzinfo durch langes Drücken oder Bewegen des Mauszeigers auf den ToolTipBox-Inhalt aktiviert wird, wird sie etwa eine Sekunde lang angezeigt. Sie können diesen Infotipp schließen, indem Sie entweder an einer anderen Stelle auf das Display tippen oder die Schaltfläche zum Schließen verwenden.
• Wenn die Aktion zum 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 das Tooltip manuell mit tooltipState.show anzuzeigen.
• Mit dem Parameter action können interaktive Elemente wie eine Schaltfläche in eine Kurzinfo eingefügt werden.
• Mit dem Parameter caretSize wird die Größe des Tooltip-Pfeils geändert.

Ergebnis

Dieses Beispiel erzeugt Folgendes:

Abbildung 4: Eine benutzerdefinierte Rich-Kurzinfo mit einer Schließen-Schaltfläche, die an ein Kamerasymbol angehängt ist.

Zusätzliche Ressourcen

• Material Design: Kurzinfos