工具提示

使用提示为按钮或其他界面元素添加上下文。 提示分为两种类型：

• 普通提示：描述图标按钮的元素或操作。
• 富提示：提供更多详细信息，例如描述功能的值。还可以包含可选的标题、链接和按钮。

图 1. 普通提示 (1) 和富文本提示 (2)。

API Surface

您可以使用 TooltipBox 可组合项在应用中实现提示。您可以使用以下主要参数控制 TooltipBox 的外观：

• positionProvider：相对于锚点内容放置提示。您通常会使用 TooltipDefaults 中的默认位置提供程序，但如果您需要自定义定位逻辑，也可以提供自己的位置提供程序。
• tooltip：包含提示内容的可组合项。您通常会使用 PlainTooltip 或 RichTooltip 可组合项。
  • 使用 PlainTooltip 描述图标按钮的元素或操作。
  • 使用 RichTooltip 提供更多详细信息，例如描述某项功能的价值。富工具提示可以包含可选的标题、链接和按钮。
• state：包含此提示的界面逻辑和元素状态的状态容器。
• content：提示所锚定的可组合项内容。

显示普通提示

使用纯文本提示简要描述界面元素。以下代码段会在图标按钮顶部显示一个普通提示，标签为“添加到收藏夹”：

@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 会生成一个包含文本“添加到收藏夹”的提示。
  • TooltipDefaults.rememberPlainTooltipPositionProvider() 为普通提示提供默认定位。
  • tooltip 是一个 lambda 函数，它使用 PlainTooltip 可组合项定义提示的内容。
  • Text(plainTooltipText) 会在提示中显示文本。
  • tooltipState 用于控制提示的状态。
• IconButton 会创建一个带有图标的可点击按钮。
  • Icon(...) 在按钮内显示心形图标。
  • 当用户与 IconButton 互动时，TooltipBox 会显示包含文本“添加到收藏夹”的提示。用户可以通过以下方式触发提示，具体取决于设备：
  • 将光标悬停在图标上
  • 在移动设备上长按该图标

结果

此示例会在图标顶部生成一个普通提示：

图 2. 当用户将鼠标悬停在心形图标上或长按该图标时，系统会显示一个纯文本提示。

显示富媒体提示

使用富提示提供有关界面元素的更多背景信息。此示例创建了一个带标题的多行富工具提示，该提示锚定到 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)
                        }
                    }
                },
            ) {
                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. 锚定到相机图标的自定义丰富提示，其中包含关闭操作。

其他资源

• Material Design：提示