徽标

徽标组件生成一个小标签，该标签附加到其子元素上。

简介

徽标是 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

🛍

最大值