Counter 数字滚动
纯原生 requestAnimationFrame 驱动的数字缓动动画，无第三方动画库依赖，配合 Hero 区块和 Dashboard 统计展示效果极佳。
预览
基础用法
组件安装次数
可用性
内置组件数
prefix 前缀（如货币符号）
separator 千分位分隔符
from 起始值
尺寸：SM / MD / LG / XL
complete 事件
变体（仅文字颜色）
安装
pnpm dlx brutx-vue@latest add counter用法
<script setup>
import { Counter } from 'brutx-ui-vue'
import { ref } from 'vue'
const counterRef = ref()
</script>
<template>
<!-- 基础用法 -->
<Counter :to="12800" suffix="+" size="lg" />
<!-- 小数点 -->
<Counter :to="99.9" :decimals="1" suffix="%" />
<!-- 手动控制 -->
<Counter ref="counterRef" :to="500" :auto-start="false" />
<button @click="counterRef.play()">开始</button>
</template>自定义组件前缀/后缀
<script setup>
import { Counter } from 'brutx-ui-vue'
import { DollarSign, Percent } from 'lucide-vue-next'
</script>
<template>
<!-- 使用组件作为前缀 -->
<Counter :to="12800" :prefix-component="DollarSign" />
<!-- 使用文本作为后缀 -->
<Counter :to="99.9" :decimals="1" suffix="%" />
<!-- 混合使用：组件前缀 + 文本后缀 -->
<Counter :to="500" :prefix-component="DollarSign" suffix="万" :animate-suffix="false" />
</template>变体
variant 仅影响数字文字颜色，方便在不同背景上突出展示统计数值。accent 为亮黄色，在浅色背景上对比度偏低，建议在深色或彩色背景上使用。
| 变体 | 说明 |
|---|---|
default | 标准前景色文字 |
primary | Primary（珊瑚色）文字 |
accent | Accent（黄色）文字 |
success | Success（绿色）文字 |
danger | Destructive（红色）文字 |
<script setup>
import { Counter } from 'brutx-ui-vue'
</script>
<template>
<div class="flex flex-wrap items-end gap-6">
<Counter :to="128" variant="default" size="lg" />
<Counter :to="128" variant="primary" size="lg" />
<Counter :to="128" variant="accent" size="lg" />
<Counter :to="128" variant="success" size="lg" />
<Counter :to="128" variant="danger" size="lg" />
</div>
</template>尺寸
| 尺寸 | 说明 |
|---|---|
sm | 小字号 |
md | 默认字号 |
lg | 大字号 |
xl | 超大字号 |
程序化控制
Counter 通过 defineExpose 暴露以下方法，允许父组件通过 ref 调用：
<script setup>
import { ref } from 'vue'
import { Counter } from 'brutx-ui-vue'
const counterRef = ref()
</script>
<template>
<Counter ref="counterRef" :to="500" :auto-start="false" />
<button @click="counterRef?.play()">开始</button>
<button @click="counterRef?.stop()">停止</button>
</template>API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
to必填 | number | — | 动画的目标数值，必填。 |
详情 | |||
from | number | undefined | 0 | 动画起始数值； play() 也从该值重新开始。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
duration | number | undefined | 2000 | 动画时长，单位为毫秒；非正数使用组件默认时长。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
decimals | number | undefined | 0 | 显示的小数位数，结果按该位数格式化。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
decimalSeparator | string | undefined | "." | 数字整数和小数部分之间显示的分隔符。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
prefix | string | undefined | "" | 显示在数值前面的文本，例如货币符号。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
suffix | string | undefined | "" | 显示在数值后面的文本，例如百分号或加号。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
prefixComponent | Component | undefined | undefined | 替代文本前缀的展示型组件；测量布局时会额外挂载一份，因此应避免内部状态和副作用。 |
详情声明类型Component | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
suffixComponent | Component | undefined | undefined | 替代文本后缀的展示型组件；测量布局时会额外挂载一份，因此应避免内部状态和副作用。 |
详情声明类型Component | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
animatePrefix | boolean | undefined | true | 存在 prefixComponent 时是否渲染该组件；关闭后显示 prefix 文本。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
animateSuffix | boolean | undefined | true | 存在 suffixComponent 时是否渲染该组件；关闭后显示 suffix 文本。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
separator | string | undefined | "," | 千位分隔符；设为空字符串可关闭千分位分组，但仍应用 decimalSeparator。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
easing | "ease-out" | "linear" | "ease-in-out" | undefined | "ease-out" | 动画进度使用的缓动函数。 |
详情声明类型"ease-out" | "linear" | "ease-in-out" | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
autoStart | boolean | undefined | true | 挂载后自动开始动画；为 false 时数值停留在 from，也不会随 to/from 更新自动播放。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
variant | "accent" | "danger" | "default" | "primary" | "success" | undefined | "default" | 数值文本的颜色变体，不改变卡片背景。 |
详情声明类型NonNullable<"default" | "primary" | "success" | "danger" | "accent" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
size | "lg" | "md" | "sm" | "xl" | undefined | "md" | 数值文字的字号预设。 |
详情声明类型NonNullable<"lg" | "sm" | "md" | "xl" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
title | string | undefined | undefined | 可选标题；提供后进入容器布局，标题插槽内容优先于该文本。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
card | boolean | undefined | false | 为数值启用带边框、内边距和阴影的卡片容器。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
valueStyle | CSSProperties | undefined | undefined | 应用到数值区域外层元素的内联样式。 |
详情声明类型CSSProperties | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
class | string | undefined | undefined | 追加到容器模式的外层容器；未启用容器模式时追加到数值文本元素。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/counter/Counter.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@complete | [] | 动画到达 to 时发出；减少动态效果偏好下直接显示目标值也会发出。 |
详情声明类型[] 来源packages/ui/src/components/counter/Counter.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#title | {} | 替换 title 属性的标题内容；提供插槽也会启用容器布局。 |
详情声明类型{}来源packages/ui/src/components/counter/Counter.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
play | () => void | 取消当前动画并从 from 重新播放；减少动态效果偏好下直接显示目标值。 |
详情声明类型() => void 来源packages/ui/src/components/counter/Counter.vue | ||
stop | () => void | 取消当前动画并停止继续更新数值。 |
详情声明类型() => void 来源packages/ui/src/components/counter/Counter.vue | ||
可访问性
- ARIA 属性：数字内容对屏幕阅读器可访问