工具提示

使用 工具提示 为按钮或其他 UI 元素添加上下文。工具提示有两种类型：

  • 普通工具提示：描述图标按钮的元素或操作。
  • 富工具提示：提供更多详细信息，例如描述功能的值。还可以包含可选的标题、链接和按钮。
Single line plain tooltip labeled (1), and a multi-line rich tooltip with a title and information block labeled (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 显示带有“添加到收藏夹”文本的工具提示。根据设备的不同，用户可以通过以下方式触发工具提示：
    • 将光标悬停在图标上方
    • 在移动设备上长按图标

结果

此示例在图标上方生成一个普通工具提示

Single-line tooltip containing the text
图 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() 为富工具提示提供定位信息。

结果

此示例生成一个带有标题并附着到信息图标的富工具提示

A multiple-line tooltip with the title
图 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 参数修改工具提示箭头的尺寸。

结果

此示例生成以下内容：

Multi-line tooltip with the title
图 4. 带有关闭操作并锚定到相机图标的自定义富工具提示。

其他资源