Badge 徽章

按钮和图标上的数字或状态标记。常用于顶部导航、消息入口、通知列表和需要提示新增内容的操作项。

基础用法

使用 value 设置徽章显示值，数值可以是 number 或 string。通过 type 可以切换不同语义颜色，也可以使用 color 自定义背景色。

¹²

³

¹

²

¹

<el-badge :value="12">
  <el-button>评论</el-button>
</el-badge>
<el-badge :value="3">
  <el-button>回复</el-button>
</el-badge>
<el-badge :value="1" type="primary">
  <el-button>任务</el-button>
</el-badge>
<el-badge :value="1" color="#626aef">
  <el-button>自定义</el-button>
</el-badge>

最大值

通过 max 设置最大展示值。只有当 value 是数字时，超过最大值才会显示为 {max}+。

⁹⁹⁺

¹⁰⁺

<el-badge :value="200" :max="99">
  <el-button>评论</el-button>
</el-badge>
<el-badge :value="100" :max="10">
  <el-button>回复</el-button>
</el-badge>

自定义显示内容

value 可以传入字符串展示自定义文案；需要更复杂的内容时，可以使用 content 插槽自定义徽章内部结构。

^new

^hot

⁹⁹

<template>
  <el-badge value="new">
    <el-button>评论</el-button>
  </el-badge>

  <el-badge value="99">
    <el-button>消息</el-button>
    <template #content="{ value }">
      <span>
        <el-icon><Message /></el-icon>
        <span>{{ value }}</span>
      </span>
    </template>
  </el-badge>
</template>

<script setup lang="ts">
import { Message } from '@element-plus/icons-vue'
</script>

小红点

使用 is-dot 可以只展示一个状态点，适合提示是否有新内容，而不强调具体数量。

查询结果

<template>
  <el-badge is-dot>
    <span>查询结果</span>
  </el-badge>

  <el-badge is-dot>
    <el-button type="primary">
      <el-icon><Share /></el-icon>
      <span>分享</span>
    </el-button>
  </el-badge>
</template>

<script setup lang="ts">
import { Share } from '@element-plus/icons-vue'
</script>

偏移量

通过 offset 设置徽章的偏移量，格式为 [left, top]，分别控制相对默认位置的水平和垂直偏移。

¹

<el-badge :value="1" :offset="[10, 5]">
  <el-button>偏移徽章</el-button>
</el-badge>

<el-badge is-dot :offset="[8, 3]">
  <el-button>偏移圆点</el-button>
</el-badge>

隐藏与零值

设置 hidden 可以隐藏徽章。show-zero 控制值为 0 时是否显示徽章，默认显示。

⁰

⁰

<el-badge :value="0">
  <el-button>显示 0</el-button>
</el-badge>
<el-badge :value="0" :show-zero="false">
  <el-button>隐藏 0</el-button>
</el-badge>
<el-badge :value="8" hidden>
  <el-button>隐藏徽章</el-button>
</el-badge>

自定义样式

通过 badge-style 和 badge-class 可以进一步控制徽章样式，适合少量业务定制场景。常规语义颜色优先使用 type 或 color。

⁶

<template>
  <el-badge :value="6" :badge-style="badgeStyle">
    <el-button>待处理</el-button>
  </el-badge>
</template>

<script setup lang="ts">
const badgeStyle = {
  backgroundColor: '#1f8f5f',
}
</script>

Badge API

Badge 属性

属性名	说明	类型	默认值
value	显示值	string | number	''
max	最大值，超过最大值会显示 {max}+，仅在 value 为数字时生效	number	99
is-dot	是否显示小圆点	boolean	false
hidden	是否隐藏徽章	boolean	false
type	徽章类型	primary | success | warning | danger | info	danger
show-zero	值为 0 时是否显示徽章	boolean	true
color	自定义背景色	string	-
offset	徽章偏移量	array	[0, 0]
badge-style	自定义徽章样式	object	-
badge-class	自定义徽章类名	string	-

Badge 插槽

插槽名	说明	类型
default	自定义默认内容	-
content	自定义显示内容	object