工具提示

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

  • 纯文本提示：描述图标按钮的元素或操作。
  • 富提示：提供更多详细信息，例如描述某个功能的值。还可以包含可选的标题、链接和按钮。
单行纯文本提示（标记为 [1]）和多行富文本提示（包含标题和信息块，标记为 [2]）。
图 1. 一个纯文本提示 (1) 和一个富文本提示 (2)。

API Surface

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

  • positionProvider：将提示放置在相对于锚定内容的位置。您通常会使用 TooltipDefaults 中的默认位置提供程序，也可以在需要自定义定位逻辑时提供自己的位置提供程序。
  • tooltip：包含提示内容的 composable。您通常使用 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"
            )
        }
    }
}

代码要点

  • TooltipBox 生成一个包含“添加到收藏夹”文字的工具提示。
  • 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"
            )
        }
    }
}

代码要点

  • TooltipBox 处理用户互动的事件监听器，并相应地更新 TooltipState。当 TooltipState 指示应显示工具提示时，工具提示 lambda 会执行，而 TooltipBox 会显示 RichTooltip。TooltipBox 充当内容和提示的锚点和容器。
    • 在本例中，相应内容是一个 IconButton 组件，可提供可点按的操作行为。当用户在触控设备上长按 TooltipBox 的内容或将鼠标指针悬停在 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(