Counter 数字滚动

纯原生 requestAnimationFrame 驱动的数字缓动动画，无第三方动画库依赖，配合 Hero 区块和 Dashboard 统计展示效果极佳。

预览

Preview

基础用法

12,800+ 0 +

组件安装次数

99.9% 0.0 %

可用性

56 0

内置组件数

prefix 前缀（如货币符号）

$9,999$ 0 ¥52,800¥ 0

separator 千分位分隔符

1,234,567 0 1.234.567 0 1234567 0

from 起始值

500 100 0 1,000

尺寸：SM / MD / LG / XL

42 0 SM

42 0 MD

42 0 LG

42 0 XL

complete 事件

100 0

变体（仅文字颜色）

128 0 default

128 0 primary

128 0 accent

128 0 success

128 0 danger

安装

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 仅影响数字文字颜色，方便在不同背景上突出展示统计数值。

变体	说明
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

方法/属性	类型	说明
play()	() => void	从 from 重新开始播放动画
stop()	() => void	立即停止动画

Props

属性	类型	默认值	说明
to	number	—	目标数值（必填）
from	number	0	起始数值
duration	number	2000	动画时长（毫秒）
decimals	number	0	小数位数
decimalSeparator	string	'.'	小数分隔符
prefix	string	''	数字前缀（如 ¥ $）
suffix	string	''	数字后缀（如 + %）
prefixComponent	Component	—	自定义前缀组件
suffixComponent	Component	—	自定义后缀组件
animatePrefix	boolean	true	是否显示自定义前缀组件（false 时显示文本前缀）
animateSuffix	boolean	true	是否显示自定义后缀组件（false 时显示文本后缀）
separator	string	','	千位分隔符，传空字符串可禁用
easing	'linear' | 'ease-out' | 'ease-in-out'	'ease-out'	缓动函数
autoStart	boolean	true	是否挂载后自动播放
size	'sm' | 'md' | 'lg' | 'xl'	'md'	字号预设
variant	'default' | 'primary' | 'accent' | 'success' | 'danger'	'default'	文字颜色变体（仅影响文字颜色，不改变背景）
title	string	—	可选标题，传入后启用容器模式
card	boolean	false	是否启用卡片容器样式
valueStyle	CSSProperties	—	数值区域内联样式
class	string	—	自定义样式类

事件

事件	参数	说明
complete	—	动画播放完毕时触发

可访问性

• ARIA 属性：数字内容对屏幕阅读器可访问