Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Badge 徽章
在按钮、图标、头像等元素的角上显示数字或小圆点,提示有未读消息、待办数量等。也可以不包内容,单独放在文字旁边。
引入
import { NsBadge } from '@ns/ui'
基础用法
把要标记的元素放进默认插槽,value 传显示的值。徽章的中心对准元素的右上角。
<script setup lang="ts">
import { NsBadge, NsButton } from '@ns/ui'
</script>
<template>
<NsBadge :value="12">
<NsButton>消息</NsButton>
</NsBadge>
</template>
包裹其他元素
默认插槽里可以放按钮、图标、头像、文字链接等任意元素,徽章都压在它的右上角。
<script setup lang="ts">
import { NsAvatar, NsBadge, NsButton, NsIcon, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap size="large" align="center">
<NsBadge :value="3">
<NsButton icon="bell" aria-label="通知" />
</NsBadge>
<NsBadge :value="7">
<NsIcon name="mail" size="xl" />
</NsBadge>
<NsBadge dot>
<NsAvatar icon="user" shape="square" />
</NsBadge>
<NsBadge :value="2" type="primary">
<NsAvatar label="张" />
</NsBadge>
<NsBadge value="new">
<a href="https://example.com" target="_blank">更新日志</a>
</NsBadge>
</NsSpace>
</template>
最大值
max 限制显示的数字,超过时显示“max+”,没超过时原样显示。只对数字生效,value 是字符串时原样显示。value 为 0 时也会显示。
<script setup lang="ts">
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<NsBadge :value="15" :max="10">
<NsButton>15,max 10</NsButton>
</NsBadge>
<NsBadge :value="100" :max="99">
<NsButton>100,max 99</NsButton>
</NsBadge>
<NsBadge :value="8" :max="99">
<NsButton>8,max 99</NsButton>
</NsBadge>
<NsBadge :value="1000">
<NsButton>1000,不限</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<NsBadge value="999" :max="99">
<NsButton>字符串不受 max 限制</NsButton>
</NsBadge>
<NsBadge value="new">
<NsButton>文字</NsButton>
</NsBadge>
<NsBadge value="热">
<NsButton>单字</NsButton>
</NsBadge>
<NsBadge :value="0">
<NsButton>值为 0</NsButton>
</NsBadge>
</NsSpace>
</NsSpace>
</template>
小圆点
dot 只显示一个小圆点,不显示数值,传了 value 也不显示。
<script setup lang="ts">
import { NsBadge, NsButton, NsIcon, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap size="large" align="center">
<NsBadge dot>
<NsButton>消息</NsButton>
</NsBadge>
<NsBadge dot :value="99">
<NsButton>传了 value 也只显示圆点</NsButton>
</NsBadge>
<NsBadge dot>
<NsIcon name="bell" size="lg" />
</NsBadge>
</NsSpace>
</template>
类型和颜色
type 有 primary、success、warning、danger、info、help 六种,不写时是红色。color 自定义背景色,优先于 type。
下面第一行是数字徽章,第二行是小圆点,从左到右是不写 type、6 种类型和自定义颜色:
<script setup lang="ts">
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<span class="row-label">数字</span>
<NsBadge :value="5">
<NsButton>不写</NsButton>
</NsBadge>
<NsBadge :value="5" type="primary">
<NsButton>主要</NsButton>
</NsBadge>
<NsBadge :value="5" type="success">
<NsButton>成功</NsButton>
</NsBadge>
<NsBadge :value="5" type="warning">
<NsButton>警告</NsButton>
</NsBadge>
<NsBadge :value="5" type="danger">
<NsButton>危险</NsButton>
</NsBadge>
<NsBadge :value="5" type="info">
<NsButton>信息</NsButton>
</NsBadge>
<NsBadge :value="5" type="help">
<NsButton>帮助</NsButton>
</NsBadge>
<NsBadge :value="5" color="#722ed1">
<NsButton>自定义</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<span class="row-label">dot</span>
<NsBadge dot>
<NsButton>不写</NsButton>
</NsBadge>
<NsBadge dot type="primary">
<NsButton>主要</NsButton>
</NsBadge>
<NsBadge dot type="success">
<NsButton>成功</NsButton>
</NsBadge>
<NsBadge dot type="warning">
<NsButton>警告</NsButton>
</NsBadge>
<NsBadge dot type="danger">
<NsButton>危险</NsButton>
</NsBadge>
<NsBadge dot type="info">
<NsButton>信息</NsButton>
</NsBadge>
<NsBadge dot type="help">
<NsButton>帮助</NsButton>
</NsBadge>
<NsBadge dot color="#722ed1">
<NsButton>自定义</NsButton>
</NsBadge>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
位置和偏移
position 指定徽章在哪个角:top-right(默认)、top-left、bottom-right、bottom-left。offset 在此基础上再偏移 [x, y] 像素,x 为正向右,y 为正向下,负数反过来。
<script setup lang="ts">
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<NsBadge :value="8">
<NsButton>右上(top-right)</NsButton>
</NsBadge>
<NsBadge :value="8" position="top-left">
<NsButton>左上(top-left)</NsButton>
</NsBadge>
<NsBadge :value="8" position="bottom-right">
<NsButton>右下(bottom-right)</NsButton>
</NsBadge>
<NsBadge :value="8" position="bottom-left">
<NsButton>左下(bottom-left)</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<NsBadge :value="8" :offset="[10, 0]">
<NsButton>向右 10px</NsButton>
</NsBadge>
<NsBadge :value="8" :offset="[0, 10]">
<NsButton>向下 10px</NsButton>
</NsBadge>
<NsBadge :value="8" :offset="[-10, 6]">
<NsButton>向左 10px、向下 6px</NsButton>
</NsBadge>
<NsBadge dot position="bottom-left" :offset="[6, -6]">
<NsButton>左下角往里收 6px</NsButton>
</NsBadge>
</NsSpace>
</NsSpace>
</template>
形状和尺寸
shape 有 circle(默认,两端圆)、rounded(小圆角)、square(直角)三种;size 有 small、default、large 三种,高度依次是 14、18、22px,小圆点直径 6、8、10px。size 不写时跟随 NsConfigProvider 的 size,都没有时是 default。
size="medium" 是旧写法,已不推荐,效果和 default 一样,旧代码不用改也能用。
下面每一行是一种形状,从左到右是 3 种尺寸,最后一个是同尺寸的小圆点:
<script setup lang="ts">
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap size="large">
<span class="row-label">circle</span>
<NsBadge :value="12" size="large">
<NsButton>large</NsButton>
</NsBadge>
<NsBadge :value="12">
<NsButton>default</NsButton>
</NsBadge>
<NsBadge :value="12" size="small">
<NsButton>small</NsButton>
</NsBadge>
<NsBadge value="new" size="large">
<NsButton>文字</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<span class="row-label">rounded</span>
<NsBadge :value="12" shape="rounded" size="large">
<NsButton>large</NsButton>
</NsBadge>
<NsBadge :value="12" shape="rounded">
<NsButton>default</NsButton>
</NsBadge>
<NsBadge :value="12" shape="rounded" size="small">
<NsButton>small</NsButton>
</NsBadge>
<NsBadge value="new" shape="rounded" size="large">
<NsButton>文字</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<span class="row-label">square</span>
<NsBadge :value="12" shape="square" size="large">
<NsButton>large</NsButton>
</NsBadge>
<NsBadge :value="12" shape="square">
<NsButton>default</NsButton>
</NsBadge>
<NsBadge :value="12" shape="square" size="small">
<NsButton>small</NsButton>
</NsBadge>
<NsBadge value="new" shape="square" size="large">
<NsButton>文字</NsButton>
</NsBadge>
</NsSpace>
<NsSpace wrap size="large">
<span class="row-label">dot</span>
<NsBadge dot size="large">
<NsButton>large</NsButton>
</NsBadge>
<NsBadge dot>
<NsButton>default</NsButton>
</NsBadge>
<NsBadge dot size="small">
<NsButton>small</NsButton>
</NsBadge>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
数字变化动画
animated 为 true 时,数值变化时新数字从下往上滚入,旧数字向上滚出。小圆点模式下没有动画。下面左边开了动画,右边没开,点按钮对比:
<script setup lang="ts">
import { ref } from 'vue'
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
const count = ref(5)
</script>
<template>
<NsSpace wrap size="large">
<NsBadge :value="count" :max="99" animated>
<NsButton>有动画</NsButton>
</NsBadge>
<NsBadge :value="count" :max="99">
<NsButton>无动画</NsButton>
</NsBadge>
<NsButton icon="plus" @click="count++">加 1</NsButton>
<NsButton icon="minus" :disabled="count <= 0" @click="count--">减 1</NsButton>
</NsSpace>
</template>
隐藏
hidden 为 true 时徽章淡出隐藏,改回 false 时缩放淡入。数字徽章和小圆点都一样。
<script setup lang="ts">
import { ref } from 'vue'
import { NsBadge, NsButton, NsSpace } from '@ns/ui'
const hidden = ref(false)
</script>
<template>
<NsSpace wrap size="large">
<NsBadge :value="3" :hidden="hidden">
<NsButton>消息</NsButton>
</NsBadge>
<NsBadge dot :hidden="hidden">
<NsButton>动态</NsButton>
</NsBadge>
<NsButton @click="hidden = !hidden">{{ hidden ? '显示' : '隐藏' }}</NsButton>
</NsSpace>
</template>
独立徽章
不写默认插槽时是独立徽章,和文字一样排在行内,垂直居中。position 对独立徽章不起作用,其他属性照常生效。
<script setup lang="ts">
import { NsBadge, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace size="large">
<span>待办 <NsBadge :value="5" /></span>
<span>新 <NsBadge dot /></span>
<span>评论 <NsBadge :value="120" :max="99" type="primary" /></span>
<span>状态 <NsBadge value="已上线" type="success" shape="rounded" /></span>
</NsSpace>
<NsSpace size="large" align="center">
<NsBadge :value="1" type="primary" size="small" />
<NsBadge :value="2" type="success" />
<NsBadge :value="3" type="warning" size="large" />
<NsBadge value="beta" type="help" shape="square" />
<NsBadge dot type="info" size="large" />
</NsSpace>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | string | number | - | 显示的值。不写且不是 dot 时不显示徽章 |
| max | number | - | 最大值,数字超过时显示“max+”。只对数字生效 |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | - | 类型颜色,不写时是红色 |
| color | string | - | 自定义背景色,优先于 type |
| dot | boolean | false | 是否显示为小圆点(不显示数值) |
| hidden | boolean | false | 是否隐藏 |
| offset | [number, number] | - | 在 position 的基础上偏移 [x, y] 像素,x 为正向右,y 为正向下 |
| shape | 'circle' | 'square' | 'rounded' | 'circle' | 形状 |
| position | 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-right' | 包裹内容时徽章所在的角,独立徽章不起作用 |
| size | 'large' | 'default' | 'small' | 'medium' | - | 尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default'。'medium' 已不推荐,等同于 'default' |
| animated | boolean | false | 数值变化时是否有滚动动画 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 被标记的内容。不写时是独立徽章 |
类型
import type { BadgeProps, BadgeType, BadgeShape, BadgePosition, BadgeSize } from '@ns/ui'
type BadgeType = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help'
type BadgeShape = 'circle' | 'square' | 'rounded'
type BadgePosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
/** @deprecated 改用 'default'。'medium' 只为兼容旧代码保留,效果和 'default' 一样 */
type BadgeSizeMedium = 'medium'
type BadgeSize = 'large' | 'default' | 'small' | BadgeSizeMedium
interface BadgeProps {
value?: string | number
max?: number
type?: BadgeType
color?: string
dot?: boolean
hidden?: boolean
offset?: [number, number]
shape?: BadgeShape
position?: BadgePosition
size?: BadgeSize
animated?: boolean
}
注意事项
- 不写默认插槽时是独立徽章,
position不起作用,徽章和文字在同一行垂直居中。 max只对数字生效。value传字符串(例如'99+'、'new')时原样显示。value为0时仍然显示“0”,不会自动隐藏。不想显示时用hidden或不传value。- 徽章用绝对定位压在内容的角上,中心对准角,有一半在内容外面。内容旁边紧挨着别的元素时,留出一点间距。
- 组件没有事件,也没有暴露方法。
- 不写
size时跟随NsConfigProvider的size,放在设了size的NsConfigProvider里时徽章会跟着变大或变小;size="medium"已不推荐,等同于size="default"。
优化点
- [ ] 支持
showZero,value为 0 时可选择隐藏 - [ ] 支持自定义徽章内容的插槽
- [x] 支持跟随 ConfigProvider 的全局尺寸