徽章

使用徽章顯示小型視覺元素，在其他可組合項上表示狀態或數值。以下是可能使用徽章的幾種常見情境：

• 通知：在應用程式圖示或通知鈴鐺上，顯示未讀通知數量。
• 訊息：表示即時通訊應用程式中有新訊息或未讀訊息。
• 狀態更新：顯示工作的狀態，例如「完成」、「進行中」或「失敗」。
• 購物車數量：顯示使用者購物車中的商品數量。
• 新內容：醒目顯示使用者可取得的新內容或功能。

圖 1. 徽章範例

API 介面

使用 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