工具提示

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

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

API 介面

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

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

顯示純文字工具提示

使用純文字工具提示簡要說明 UI 元素。這個程式碼片段會在標示為「加入我的最愛」的圖示按鈕上方，顯示純文字工具提示：

@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 會產生工具提示，顯示「新增至我的最愛」文字。
  • 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(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

程式碼重點

  • TooltipBox 會處理使用者互動的事件監聽器，並據此更新 TooltipState。當 TooltipState 指出應顯示工具提示時，工具提示 lambda 會執行，而 TooltipBox 會顯示 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. 以攝影機圖示為錨點的自訂豐富工具提示，並提供關閉動作。

其他資源