徽章

使用徽章在其他可組合函式上顯示小型視覺元素，表示狀態或數值。以下列舉幾種可能適合使用徽章的情況：

  • 通知：在應用程式圖示或通知鈴上顯示未讀通知數量。
  • 訊息：顯示即時通訊應用程式中的新訊息或未讀訊息。
  • 狀態更新：顯示工作狀態，例如「完成」、「進行中」或「失敗」。
  • 購物車數量：顯示使用者購物車中的商品數量。
  • 新內容：強調使用者可用的新內容或功能。
徽章元件的其他範例。
圖 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. 最簡單的徽章實作方式。

詳細範例

下列程式碼片段示範如何顯示徽章中的值，以回應使用者動作。

@Composable
fun BadgeInteractiveExample() {
    var itemCount by remember { mutableStateOf(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. 顯示購物車中商品數量的徽章。

其他資源