工具提示

使用工具提示，為按鈕或其他 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(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}

Tooltips.kt

程式碼的重點

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

結果

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

包含文字的單行工具提示
圖 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(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

程式碼的重點

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

結果

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

多行工具提示，標題為
圖 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)
                        }
                    }
                },
                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

程式碼的重點

  • RichToolTip 會顯示含有標題和關閉動作的工具提示。
  • 啟用時，無論是長按或以滑鼠游標懸停在 ToolTipBox 內容上，工具提示都會顯示約一秒鐘。您可以輕觸螢幕上的其他位置，或使用關閉動作按鈕來關閉這個工具提示。
  • 執行關閉動作時，系統會啟動協同程式來呼叫 tooltipState.dismiss。這樣可確保在顯示工具提示時，不會阻斷動作執行。
  • onClick = coroutineScope.launch { tooltipState.show() } } 會啟動協同程式，以便使用 tooltipState.show 手動顯示工具提示。
  • action 參數可讓您將互動元素新增至工具提示 (例如按鈕)。
  • caretSize 參數可修改工具提示箭頭的大小。

結果

這個範例會產生以下內容：

含有標題的多行工具提示
圖 4. 自訂的豐富工具提示，其中包含錨定在相機圖示上的略過動作。

其他資源