工具提示

使用工具提示為按鈕或其他 UI 元素新增背景資訊。工具提示分為兩種類型：

  • 一般工具提示：說明圖示按鈕的元素或動作。
  • 豐富的工具提示：提供更多詳細資料，例如說明功能價值。也可以加入選用的標題、連結和按鈕。
單行純文字工具提示標示為 (1)，多行複合式工具提示則包含標題和資訊區塊，標示為 (2)。
圖 1. 一般工具提示 (1) 和豐富工具提示 (2)。

API 介面

您可以使用 TooltipBox 可組合項，在應用程式中實作工具提示。您可以使用下列主要參數控制 TooltipBox 外觀：

  • positionProvider：相對於錨定內容放置工具提示。您通常會使用 TooltipDefaults 的預設位置提供者，也可以視需要提供自訂位置邏輯。
  • tooltip：包含工具提示內容的可組合函式。您通常會使用 PlainTooltip 或 RichTooltip 可組合項。
    • 使用 PlainTooltip 描述圖示按鈕的元素或動作。
    • 使用 RichTooltip 提供更多詳細資料，例如說明功能價值。豐富工具提示可包含選用標題、連結和按鈕。
  • state：狀態容器，包含這個工具提示的 UI 邏輯和元素狀態。
  • content：工具提示錨定的可組合項內容。

顯示一般工具提示

使用一般工具提示簡短說明 UI 元素。這個程式碼片段會在圖示按鈕上方顯示純文字工具提示，標籤為「Add to favorites」：

@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"
            )
        }
    }
}

程式碼重點

  • TooltipBox 會產生文字為「Add to favorites」的工具提示。
  • IconButton 會建立含有圖示的可點擊按鈕。
    • Icon(...) 會在按鈕中顯示愛心圖示。
    • 當使用者與 IconButton 互動時，TooltipBox 會顯示文字為「加入我的收藏」的工具提示。視裝置而定，使用者可以透過下列方式觸發工具提示：
    • 將游標懸停在圖示上
    • 在行動裝置上長按圖示

結果

這個範例會在圖示上方產生一般工具提示：

單行工具提示，內含「加入我的收藏」文字，顯示在心形圖示上方。將滑鼠游標懸停在圖示上或長按圖示，即可查看工具提示。
圖 2. 使用者將滑鼠游標懸停在愛心圖示上或長按該圖示時，會顯示純文字工具提示。

顯示豐富的工具提示

使用豐富工具提示，提供 UI 元素的額外背景資訊。以下範例會建立多行豐富工具提示，並將標題錨定至 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"
            )
        }
    }
}

程式碼重點

  • TooltipBox 會處理使用者互動的事件監聽器，並據此更新 TooltipState。當 TooltipState 指出應顯示工具提示時，工具提示 lambda 會執行，且 TooltipBox 會顯示 RichTooltip。TooltipBox 會做為內容和工具提示的錨點和容器。
    • 在本例中，內容是 IconButton 元件，可提供可輕觸的動作行為。在 TooltipBox 內容中的任何位置長按 (在觸控裝置上) 或懸停 (使用滑鼠游標)，系統就會顯示工具提示，提供更多資訊。
  • RichTooltip 可組合項會定義工具提示的內容，包括標題和內文。TooltipDefaults.rememberRichTooltipPositionProvider() 提供豐富工具提示的定位資訊。

結果

這個範例會產生一個豐富的工具提示，其中包含附加到資訊圖示的標題：

標題為「Rich Tooltip」的多行工具提示，資訊圖示上方有一行文字。
圖 3 含有標題和資訊圖示的豐富工具提示。

自訂豐富工具提示

這段程式碼片段會顯示豐富工具提示，其中包含標題、自訂動作，以及顯示在相機圖示按鈕上方的自訂插入點 (箭頭)：

@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"
            )
        }
    }
}

程式碼重點

  • RichTooltip 會顯示工具提示，其中包含標題和關閉動作。
  • 長按或將滑鼠游標懸停在 TooltipBox 內容上，即可啟用工具提示，顯示時間約為一秒。輕觸螢幕其他位置或使用關閉動作按鈕，即可關閉這則工具提示。
  • 執行關閉動作時，系統會啟動協同程式來呼叫 tooltipState.dismiss。這可驗證顯示工具提示時，動作執行不會遭到封鎖。
  • onClick = coroutineScope.launch { tooltipState.show() } } 會啟動協同程式，使用 tooltipState.show 手動顯示工具提示。
  • action 參數可讓您在工具提示中加入互動元素，例如按鈕。
  • caretSize 參數會修改工具提示箭頭的大小。

結果

這個範例會產生下列輸出內容：

多行工具提示，標題為「自訂豐富工具提示」，並附有關閉按鈕。工具提示固定在相機圖示上。
圖 4. 自訂豐富工具提示，其中包含錨定在相機圖示上的關閉動作。

其他資源