徽章

Badge 元件會產生一個小標籤，附加在其子元素上。

簡介

徽章是 UI 元素的小型描述符。它通常位於元素之上或附近，並透過顯示數字、圖示或其他簡短字元集來指示該元素的狀態。

Badge 元件會建立一個徽章，應用於其子元素。

元件

import { Badge } from '@mui/base/Badge';

Badge 包裹著它所附加的 UI 元素。

剖析

Badge 元件由一個根 <span> 組成，其中包含 Badge 所附加的元素，後跟一個 <span> slot 來表示 Badge 本身

<span class="BaseBadge-root">
  <!-- the element the badge is attached to is nested here -->
  <span class="BaseBadge-badge">badge content</span>
</span>

自訂結構

使用 slots prop 來覆寫 root 或任何其他內部 slot

<Badge slots={{ root: 'div', badge: 'div' }} />

使用 slotProps prop 將自訂 props 傳遞到內部 slot。以下程式碼片段將名為 my-badge 的 CSS 類別應用於 badge slot

<Badge slotProps={{ badge: { className: 'my-badge' } }} />

搭配 TypeScript 使用

在 TypeScript 中，您可以將 slots.root 中使用的自訂元件類型指定為unstyled 元件的泛型參數。這樣，您可以安全地在元件上直接提供自訂 root 的 props

<Badge<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />

相同的道理也適用於自訂 primitive 元素的特定 props

<Badge<'img'> slots={{ root: 'img' }} src="badge.png" />

Hook

import { useBadge } from '@mui/base/useBadge';

useBadge hook 讓您可以將 Badge 的功能應用於完全自訂的元件。它會傳回要放置在自訂元件上的 props，以及代表元件內部狀態的欄位。

Hooks *不* 支援slot props，但它們支援自訂 props。

自訂

徽章內容

badgeContent prop 定義徽章內顯示的內容。當此內容為數字時，還有其他 props 可用於進一步自訂 — 請參閱下方的數字徽章區段。

以下範例示範如何建立和樣式化附加到通用 box 元素的典型數字徽章

徽章可見性

您可以使用 invisible prop 控制徽章的可見性。將徽章設定為 invisible 並不會真正隱藏它 — 相反地，此 prop 會將 BaseBadge-invisible 類別新增至徽章，您可以使用樣式來以您偏好的方式隱藏它

數字徽章

當 badgeContent 為數字時，以下 props 很有用。

showZero prop

預設情況下，當 badgeContent={0} 時，徽章會自動隱藏。您可以使用 showZero prop 覆寫此行為

max prop

您可以使用 max prop 為 badgeContent 設定最大值。預設值為 99。

無障礙功能

螢幕閱讀器可能無法為使用者提供足夠的徽章內容資訊。為了讓您的徽章易於存取，您必須使用 aria-label 提供完整描述，如下方範例所示