标志

使用标记显示一个小的视觉元素，以在另一个可组合项上表示状态或数值。以下是您可能会使用标记的一些常见场景：

• 通知：在应用图标或通知铃铛上显示未读通知的数量。
• 信息：表示聊天应用中有新信息或未读信息。
• 状态更新：显示任务的状态，例如“完成”“进行中”或“失败”。
• 购物车数量：显示用户购物车中的商品数量。
• 新内容：突出显示用户可使用的新内容或新功能。

图 1. 徽章示例

API Surface

使用 BadgedBox 可组合项在应用中实现标记。它最终是一个容器。您可以使用以下两个主要参数控制其外观：

• content：BadgedBox 包含的可组合内容。通常为 Icon。
• badge：在内容上显示为标记的可组合项。 通常是专用的 Badge 可组合项。

基本示例

以下代码段展示了 BadgedBox 的基本实现：

@Composable
fun BadgeExample() {
    BadgedBox(
        badge = {
            Badge()
        }
    ) {
        Icon(
            imageVector = Icons.Filled.Mail,
            contentDescription = "Email"
        )
    }
}
Badges.kt

此示例显示了一个与提供的 Icon 可组合项重叠的标记。请注意代码中的以下内容：

• BadgedBox 用作整体容器。
• BadgedBox 的 badge 参数的实参为 Badge。 由于 Badge 本身没有参数，因此应用会显示默认标记，即一个小红圈。
• Icon 用作 BadgedBox 的 content 形参的实参。它是显示标记的图标。在本例中，它是一个邮件图标。

如下所示：

图 2. 最简单的标记实现。

重要提示： 您可以将任何可组合项传递给 BadgedBox 可组合项的内容槽。因此，您可以创建一个显示在 Button、Image 或任何其他可组合项上的标记。

详细示例

以下代码段演示了如何在标记中显示响应用户操作的值。

@Composable
fun BadgeInteractiveExample() {
    var itemCount by remember { mutableIntStateOf(0) }

    Column(
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        BadgedBox(
            badge = {
                if (itemCount > 0) {
                    Badge(
                        containerColor = Color.Red,
                        contentColor = Color.White
                    ) {
                        Text("$itemCount")
                    }
                }
            }
        ) {
            Icon(
                imageVector = Icons.Filled.ShoppingCart,
                contentDescription = "Shopping cart",
            )
        }
        Button(onClick = { itemCount++ }) {
            Text("Add item")
        }
    }
}
Badges.kt

此示例实现了一个购物车图标，该图标带有显示用户购物车中商品数量的标记。

• 仅当商品数量大于 0 时，系统才会显示 BadgedBox。
• containerColor 和 contentColor 的参数用于控制标记的外观。
• Badge 的内容槽的 Text 可组合项会显示在标记内。在本例中，它会显示购物车中的商品数量。

此实现如下所示：

图 3. 显示购物车中商品数量的标志。

其他资源

• Material 3 - 标记
• BadgedBox
• Badge