xtf-badge

组件说明

xtf-badge 是徽标组件，用于在元素角落或独立位置展示数字、文字、图标或圆点提示。支持多种视觉变体（实心、柔和、描边、玻璃、气泡）、9 个定位方向、脉冲/弹跳/波纹动画和独立模式，适用于消息未读数、状态标记和新功能提示等场景。

基础用法

1. 数字徽标

通过 value 设置数字，包裹目标元素即可在右上角显示徽标：

vue

<template>
  <view style="display: flex; gap: 32rpx; align-items: center">
    <xtf-badge :value="5">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="120" :max="99">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="0" show-zero>
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
  </view>
</template>

2. 圆点与文字徽标

通过 dot 显示圆点提示，通过 text 显示自定义文字：

vue

<template>
  <view style="display: flex; gap: 32rpx; align-items: center">
    <xtf-badge dot>
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge text="新">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge text="HOT" theme="danger">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
  </view>
</template>

3. 主题色与变体

通过 theme 切换主题色，通过 variant 切换视觉风格：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center; flex-wrap: wrap">
    <xtf-badge :value="3" theme="primary" variant="solid">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="3" theme="danger" variant="soft">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="3" theme="success" variant="outline">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="3" theme="warning" variant="glass">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="3" theme="info" variant="bubble">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
  </view>
</template>

4. 位置与偏移

通过 position 设置徽标在目标元素上的位置（9 个方向），通过 offsetX / offsetY 微调偏移：

vue

<template>
  <view style="display: flex; gap: 32rpx; align-items: center">
    <xtf-badge dot position="top-left">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge dot position="top-right">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge dot position="bottom-right">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="8" position="top-right" :offset-x="4" :offset-y="-4">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
  </view>
</template>

5. 动画与独立模式

通过 motion 设置动画效果（pulse / bounce / wave），通过 standalone 使徽标脱离目标元素独立展示：

vue

<template>
  <view style="display: flex; gap: 32rpx; align-items: center">
    <xtf-badge :value="6" motion="pulse">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="3" motion="bounce">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge :value="9" motion="wave" theme="danger">
      <view style="width: 80rpx; height: 80rpx; background: #f0f0f0; border-radius: 16rpx" />
    </xtf-badge>
    <xtf-badge text="NEW" standalone theme="danger" />
  </view>
</template>

全部属性

属性	类型	默认值	作用描述	适用范围
`value`	`String \| Number`	`''`	徽标数字值，超过 `max` 显示 `N+`	数字徽标
`text`	`String`	`''`	自定义文字内容，优先级高于 `value`	文字徽标
`icon`	`String`	`''`	徽标图标名，支持 `xtf-icon` 图标库	图标徽标
`iconPosition`	`String`	`'start'`	图标位置：`'start'` 左侧 / `'end'` 右侧	控制图标方向
`iconSize`	`String \| Number`	`''`	图标大小，默认跟随字号	自定义图标大小
`dot`	`Boolean`	`false`	是否显示为圆点模式	简约提示
`showZero`	`Boolean`	`false`	`value` 为 0 时是否显示	需要显示 0 的场景
`max`	`String \| Number`	`99`	数字最大值，超过显示 `N+`	控制溢出显示
`size`	`String`	`''`	徽标尺寸：`'sm'` / `'md'` / `'lg'`	控制徽标大小
`theme`	`String`	`'primary'`	主题色：`'primary'` / `'success'` / `'warning'` / `'danger'` / `'info'` / `'inverse'`	切换主题色
`color`	`String`	`''`	自定义背景色，设置后 `theme` 失效	精确控制颜色
`softColor`	`String`	`''`	`soft` 变体的自定义背景色	精确控制柔和色
`textColor`	`String`	`''`	自定义文字颜色	精确控制文字色
`borderColor`	`String`	`''`	自定义边框颜色	精确控制边框色
`bubbleEndColor`	`String`	`''`	`bubble` 变体渐变结束色	精确控制气泡渐变
`variant`	`String`	`'solid'`	视觉变体：`'solid'` / `'soft'` / `'outline'` / `'glass'` / `'bubble'`	切换视觉风格
`shape`	`String`	`'pill'`	形状：`'pill'` 胶囊 / `'rounded'` 圆角 / `'square'` 方形	切换形状
`position`	`String`	`'top-right'`	徽标位置：`'top-left'` / `'top-center'` / `'top-right'` / `'middle-left'` / `'center'` / `'middle-right'` / `'bottom-left'` / `'bottom-center'` / `'bottom-right'`	控制徽标位置
`motion`	`String`	`''`	动画效果：`'pulse'` 脉冲 / `'bounce'` 弹跳 / `'wave'` 波纹	吸引注意力
`standalone`	`Boolean`	`false`	是否独立模式，不依赖包裹元素	独立展示徽标
`inset`	`Boolean`	`false`	是否内缩显示，徽标略微缩小	内嵌样式
`offsetX`	`String \| Number`	`0`	水平偏移量（rpx）	微调水平位置
`offsetY`	`String \| Number`	`0`	垂直偏移量（rpx）	微调垂直位置
`clickable`	`Boolean`	`false`	是否可点击	徽标可交互场景
`ringColor`	`String`	`''`	自定义外环/边框颜色	精确控制外环色
`showBorder`	`Boolean`	`true`	是否显示边框	隐藏边框
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`click`	点击徽标时触发（需 `clickable` 为 `true`）	`(event)`	原生点击事件对象

插槽

插槽名	说明
默认插槽	徽标所依附的内容；`standalone` 为 `false` 时，徽标按 `position` 覆盖在该内容上。

vue

<template>
  <xtf-badge :value="3" theme="danger">
    <xtf-button label="待处理订单" type="light" />
  </xtf-badge>
</template>

主题说明

徽标圆角使用 var(--xtf-badge-radius)
徽标边框使用 var(--xtf-badge-ring)
solid 变体阴影使用 var(--xtf-badge-solid-shadow)
soft 变体背景使用各主题的 *-soft CSS 变量
glass 变体背景使用 var(--xtf-color-glass)，模糊使用 var(--xtf-badge-glass-blur)，边框使用 var(--xtf-badge-glass-border)
bubble 变体边框使用 var(--xtf-badge-bubble-border)，内阴影使用 var(--xtf-badge-bubble-inset-shadow)
文字颜色默认使用 var(--xtf-badge-text)
点击缩放使用 var(--xtf-motion-active-scale)

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-badge ​

组件说明 ​

基础用法 ​

1. 数字徽标 ​

2. 圆点与文字徽标 ​

3. 主题色与变体 ​

4. 位置与偏移 ​

5. 动画与独立模式 ​

全部属性 ​

事件 ​

插槽 ​

主题说明 ​