CountTo 数字滚动

17:06

说明

数字滚动组件：在 duration 内把数值从 start-val 缓动到 end-val（start-val 大于 end-val 时即倒计时），支持小数位、千位分隔符，以及字号 / 颜色 / 加粗等文字样式。autoplay 控制挂载后是否自动开始，也可通过 ref 调用 start / stop / reStart / resume / reset 手动控制。

兼容性

平台	支持情况
App	✅ 支持（根节点为块级 flex，多个数字滚动需自行包裹容器才能同行）
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

默认从 0 滚动到 end-val，自动开始，使用缓动结尾。

查看源码

<template>
    <ux-count-to :end-val="965"></ux-count-to>
</template>

自定义起止值

通过 start-val / end-val 指定起止数值，支持倒计时。

查看源码

<template>
    <ux-count-to :start-val="100" :end-val="0"></ux-count-to>
    <view class="gap"></view>
    <ux-count-to :start-val="0" :end-val="9999"></ux-count-to>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

千位分隔符

通过 separator 为千位以上数字添加分隔符。

查看源码

<template>
    <ux-count-to :end-val="233321.05" separator=","></ux-count-to>
</template>

显示小数

通过 decimals 控制小数位数，decimal 自定义小数点符号。

查看源码

<template>
    <ux-count-to :end-val="12345.678" :decimals="2"></ux-count-to>
    <view class="gap"></view>
    <ux-count-to :end-val="12345.678" :decimals="2" decimal="."></ux-count-to>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

自定义样式

通过 color / font-size / bold 自定义文字样式。

查看源码

<template>
    <ux-count-to :end-val="8888" color="#2979ff" :font-size="30" :bold="true"></ux-count-to>
    <view class="gap"></view>
    <ux-count-to :end-val="8888" color="#fa3534"></ux-count-to>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

关闭缓动

use-easing=false 时数字匀速增长，无缓动结尾效果。

查看源码

<template>
    <ux-count-to :end-val="5000" :use-easing="false"></ux-count-to>
</template>

动画控制

通过 duration 控制滚动时长（ms），autoplay 控制是否自动开始，也可手动触发开始。

查看源码

<template>
    <ux-count-to ref="countToRef" :end-val="965" :duration="rollDuration" :autoplay="rollAutoPlay"></ux-count-to>
    <view class="gap"></view>
    <view class="btn-row">
        <view class="btn" @click="startRoll"><text class="btn-text">开始</text></view>
        <view class="btn" @click="toggleAutoPlay"><text class="btn-text">{{ rollAutoPlay ? '自动开' : '自动关' }}</text></view>
        <view class="btn" @click="setDuration(500)"><text class="btn-text">500ms</text></view>
        <view class="btn" @click="setDuration(2000)"><text class="btn-text">2000ms</text></view>
        <view class="btn" @click="setDuration(5000)"><text class="btn-text">5000ms</text></view>
    </view>
</template>

<script setup lang="uts">
const countToRef = ref<any>();
const rollDuration = ref<number>(2000);
const rollAutoPlay = ref<boolean>(true);

function startRoll(): void {
    countToRef.value?.start();
}

function toggleAutoPlay(): void {
    rollAutoPlay.value = !rollAutoPlay.value;
}

function setDuration(ms: number): void {
    rollDuration.value = ms;
    countToRef.value?.start();
}
</script>

<style scoped>
.gap {
    height: 20px;
}
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 8px;
}
.btn {
    display: flex;
    flex-direction: row;
    align-items: center;
    justify-content: center;
    padding: 4px 12px;
    margin-right: 8px;
    margin-bottom: 8px;
    border-radius: 4px;
    background-color: #ecf5ff;
}
.btn-text {
    font-size: 13px;
    color: #2979ff;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
startVal	开始的数值，默认从0增长到某一个数	number | string	0	-
endVal	要滚动的目标数值	number | string	0	-
duration	滚动到目标数值的动画持续时间，单位为毫秒（ms）	number | string	2000	-
autoplay	设置数值后是否自动开始滚动	boolean	true	-
decimals	要显示的小数位数	number | string	0	-
useEasing	是否在即将到达目标数值的时候，使用缓慢滚动的效果	boolean	true	-
decimal	十进制分割符号	number | string	'.'	-
color	字体颜色	string	''	-
fontSize	字体大小	number | string	DEFAULT_FONT_SIZE	-
bold	是否加粗字体	boolean	false	-
separator	千位分隔符，类似金额的分割(￥23,321.05中的",")	string	''	-

Events

事件名	说明	回调参数	版本
end	数值滚动到目标值时触发	-	-

Slots

ux-count-to 无插槽。

注意事项

1. endVal 或 startVal 变化且 autoplay 为 true 时会自动重新滚动；autoplay 为 false 时初始只显示 startVal，需通过 ref 调用 start() 开始。
2. decimals 默认 0，此时小数部分会被舍入而不显示；需要小数请显式设置 decimals，并用 decimal 指定小数点符号（默认 .）。
3. separator 只作用于整数部分的千位分隔（如 233,321），小数位仍由 decimals 控制。
4. useEasing 为 true 时以指数缓出收尾，为 false 时全程匀速。
5. end 事件在滚动到目标值（动画结束）时触发一次。
6. fontSize 未显式传入时依次回退全局配置 componentProps['ux-count-to'].fontSize 与内建默认 25px；color 未传入时取主题主色。
7. 组件用 setTimeout 模拟 requestAnimationFrame（约 60fps）驱动动画，duration 为滚动总时长。
8. App 端根节点为块级 flex，H5 / 微信小程序为 inline-flex；多个数字滚动在 App 端同行显示需自行包裹容器。