Countup 数字动画

数字动画组件用于从起始值平滑递增到目标值，支持自定义时长、缓动函数、千分位格式、前缀后缀等。

基础用法

默认从 0 计数到 100，动画时长 2000ms。

<TCountup />

自定义目标值

通过 modelValue prop 设置目标数值（支持 v-model 动态更新）。

<TCountup :model-value="9999" />

动画时长

通过 duration 控制动画持续时间（毫秒）。

<TCountup :model-value="500" :duration="500" />
<TCountup :model-value="500" :duration="2000" />
<TCountup :model-value="500" :duration="5000" />

起始值与延迟

• start：起始数值（默认 0）
• delay：延迟开始动画（毫秒）

<TCountup :model-value="1000" :start="500" />
<TCountup :model-value="100" :delay="1000" />

前缀与后缀

通过 prefix 和 suffix 在数值前后添加文字。

<TCountup :model-value="99" suffix="%" />
<TCountup :model-value="5000" prefix="¥" separator="," />
<TCountup :model-value="128" prefix="第 " suffix=" 位" />

小数位数

通过 decimals 控制小数位，decimal 设置小数分隔符。

<TCountup :model-value="1234.5678" :decimals="2" />
<TCountup :model-value="99.99" :decimals="2" separator="." decimal="," />

千分位分组

通过 useGrouping（默认 true）和 separator 控制千分位分隔样式。

<TCountup :model-value="1234567" separator="," />
<TCountup :model-value="1234567" separator="." />
<TCountup :model-value="1234567" separator=" " />

缓动函数

支持三种缓动类型：linear、easeOutQuad（默认）、easeOutCubic。

<TCountup :model-value="1000" easing="linear" />
<TCountup :model-value="1000" easing="easeOutQuad" />
<TCountup :model-value="1000" easing="easeOutCubic" />

可见性触发

配合 observeVisibility prop，组件仅在进入视口时才开始动画，适合页面底部的大数字展示。

<TCountup :model-value="10000" observe-visibility separator="," />

程序化控制

通过 :key 强制重建组件或调用 restart() 方法重置并重新播放动画。更新 modelValue 后也会自动重播。

<script setup>
import { ref } from 'vue'

const docTargetVal = ref(8888)
const docMountKey = ref(0)
function docRestart() { docMountKey.value++ }
</script>

<template>
  <TCountup :key="docMountKey" :model-value="docTargetVal" separator="," />
  <button @click="docTargetVal = Math.floor(Math.random() * 100000)">随机目标值</button>
  <button @click="docRestart">重新播放</button>
</template>

API

Props

Prop	说明	类型	默认值
modelValue	目标数值	number	100
start	起始数值	number	0
duration	动画持续时间（毫秒）	number	2000
delay	延迟开始（毫秒）	number	0
decimals	小数位数	number	0
separator	千分位分隔符	string	','
decimal	小数分隔符	string	'.'
prefix	前缀文字	string	''
suffix	后缀文字	string	''
easing	缓动函数	'linear' | 'easeOutQuad' | 'easeOutCubic'	'easeOutQuad'
useGrouping	是否启用千分位分组	boolean	true
observeVisibility	是否在可见时才开始动画	boolean	false

暴露的方法与属性

通过 ref 可访问以下内容：

名称	说明	类型
restart()	重置并重新播放动画	() => void
currentValue	当前动画数值（响应式只读）	ComputedRef<number>

Events

事件	说明	参数
finished	动画播放完成时触发	—
update:modelValue	当通过 v-model 更新目标值时触发	value: number