徽章

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

簡介

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

基本用法

import Badge from '@mui/joy/Badge';

徽章元件會包裝在其附加的 UI 元素周圍。它的預設外觀是在應用程式的 primary 色彩中，位於其附加元素的右上角的點。

🛒

<Badge>
  <Typography sx={{ fontSize: 'xl' }}>🛒</Typography>
</Badge>

<Badge>
  <Typography sx={{ fontSize: 'xl' }}>🛒</Typography>
</Badge>

按下 Enter 開始編輯

內容

使用字串或數字作為 badgeContent 屬性的值，以在徽章內顯示內容。

🛍

🔔

❕

🪫

<Badge badgeContent={4}>
  <Typography sx={{ fontSize: 'xl' }}>🛍</Typography>
</Badge>
<Badge badgeContent="❕">
  <Typography sx={{ fontSize: 'xl' }}>🔔</Typography>
</Badge>
<Badge variant="plain" color="danger" badgeContent={<Warning />}>
  <Typography sx={{ fontSize: 'xl' }}>🪫</Typography>
</Badge>

<Badge badgeContent={4}>
  <Typography sx={{ fontSize: 'xl' }}>🛍</Typography>
</Badge>
<Badge badgeContent="❕">
  <Typography sx={{ fontSize: 'xl' }}>🔔</Typography>
</Badge>
<Badge variant="plain" color="danger" badgeContent={<Warning />}>
  <Typography sx={{ fontSize: 'xl' }}>🪫</Typography>
</Badge>

按下 Enter 開始編輯

數字

當 badgeContent 為數字時，以下屬性非常有用。

showZero

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

🛍

顯示零

最大值

使用 max 屬性將內容限制為最大數值。

9999+999+

<Badge badgeContent={99}>
  <MailIcon />
</Badge>
<Badge badgeContent={100} badgeInset="0 -6px 0 0">
  <MailIcon />
</Badge>
<Badge badgeContent={1000} max={999} badgeInset="0 -12px 0 0">
  <MailIcon />
</Badge>

<Badge badgeContent={99}>
  <MailIcon />
</Badge>
<Badge badgeContent={100} badgeInset="0 -6px 0 0">
  <MailIcon />
</Badge>
<Badge badgeContent={1000} max={999} badgeInset="0 -12px 0 0">
  <MailIcon />
</Badge>

按下 Enter 開始編輯

客製化

變體

徽章元件支援 Joy UI 的四種全域變體：solid（預設）、soft、outlined 和 plain。

💌

<Badge badgeContent={1} variant="solid">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={2} variant="soft">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={3} variant="outlined">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={4} variant="plain">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

<Badge badgeContent={1} variant="solid">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={2} variant="soft">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={3} variant="outlined">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={4} variant="plain">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

按下 Enter 開始編輯

尺寸

徽章元件有三種尺寸：sm、md（預設）和 lg

💌

<Badge badgeContent={10} size="sm">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={20} size="md">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={30} size="lg">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

<Badge badgeContent={10} size="sm">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={20} size="md">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={30} size="lg">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

按下 Enter 開始編輯

色彩

主題中包含的每個調色盤都可通過 color 屬性使用。

💌

<Badge badgeContent={'P'} color="primary">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'N'} color="neutral">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'D'} color="danger">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'S'} color="success">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'W'} color="warning">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

<Badge badgeContent={'P'} color="primary">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'N'} color="neutral">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'D'} color="danger">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'S'} color="success">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>
<Badge badgeContent={'W'} color="warning">
  <Typography sx={{ fontSize: 'xl' }}>💌</Typography>
</Badge>

按下 Enter 開始編輯

可見性

使用 invisible 屬性來控制徽章的可見性。

🛍

<Badge badgeContent={12} invisible={invisible}>
  <Typography sx={{ fontSize: 'xl' }}>🛍</Typography>
</Badge>
<Switch
  startDecorator="invisible"
  checked={invisible}
  onChange={(event) => setInvisible(event.target.checked)}
  variant={invisible ? 'solid' : 'outlined'}
/>

<Badge badgeContent={12} invisible={invisible}>
  <Typography sx={{ fontSize: 'xl' }}>🛍</Typography>
</Badge>
<Switch
  startDecorator="invisible"
  checked={invisible}
  onChange={(event) => setInvisible(event.target.checked)}
  variant={invisible ? 'solid' : 'outlined'}
/>

按下 Enter 開始編輯

位置

預設情況下，徽章位於其附加元素的右上角。使用 anchorOrigin 屬性根據其 vertical（頂部或底部）和 horizontal（左側或右側）位置來更改徽章的位置。嘗試點擊下方示範中的箭頭來更改徽章的位置

<Badge
  anchorOrigin={{
    vertical: 'top',
    horizontal: 'right',
  }}
>

內縮

使用 badgeInset 屬性來微調徽章相對於其附加元素的位置。此屬性接受由以 px、%、em 或 rem 為單位的數字組成的字串。（此語法對應於 inset CSS 屬性。）

此字串定義了從徽章的anchorOrigin 的內縮—例如，下面的示範將徽章沿垂直和水平軸向其子元素的中心推進 14%（相對於右上角）

<Badge badgeInset="14%" color="danger">
  <Avatar src="/static/images/avatar/1.jpg" />
</Badge>

<Badge badgeInset="14%" color="danger">
  <Avatar src="/static/images/avatar/1.jpg" />
</Badge>

按下 Enter 開始編輯

如果您將兩個單位數字傳遞給 badgeInset 屬性—例如 "50px 10px"—則第一個數字適用於垂直軸，第二個適用於水平軸。如果您將四個單位數字傳遞給屬性—例如 "0 -10px 0 5px"，它們將從頂部開始順時針應用。

無障礙功能

螢幕閱讀器可能無法為使用者提供有關徽章內容的足夠資訊。為了使您的徽章具有無障礙功能，您必須使用 aria-label 提供完整的描述，如下面的示範所示

<IconButton color="neutral" aria-label={notificationsLabel(100)}>
  <Badge badgeContent={100} badgeInset="-20%">
    <MailIcon />
  </Badge>
</IconButton>

<IconButton color="neutral" aria-label={notificationsLabel(100)}>
  <Badge badgeContent={100} badgeInset="-20%">
    <MailIcon />
  </Badge>
</IconButton>

按下 Enter 開始編輯

結構

徽章元件由一個根 <span> 組成，該根 <span> 容納了徽章所附加的元素，後跟一個 <span> 來表示徽章本身

<span class="MuiBadge-root">
  <!-- the element the Badge is attached to -->
  <span class="MuiBadge-badge">
    <!-- Badge content -->
  </span>
</span>

API

請參閱下面的文件，以獲取此處提及的元件的所有屬性和類別的完整參考。

<Badge />

徽章

Playground

showZero

🛍

最大值