1. 数字滚动这件小事，为什么值得单独拎出来说

做前端这些年，有一个需求出现的频率高得离谱，但每次实现起来又总觉得差点意思——数字滚动动画。比如后台管理系统的数据看板，一打开页面，总营业额从 0 一路跳到 128,456；比如活动页面的倒计时或者中奖金额展示，数字得有个"滚动"的过程，直接静态显示总觉得少了点仪式感。这个需求看起来简单，但真动手写的时候，你会发现要考虑的东西比想象中多：缓动函数怎么选、小数位怎么处理、千分位分隔符怎么加、滚动过程中数字跳动会不会闪、组件卸载时定时器怎么清理……

我最早接触这类需求的时候，也是手写requestAnimationFrame配合setInterval硬撸，结果就是每个项目都要复制一遍类似的代码，改起来还容易漏掉边界情况。后来用上了vue-countTo这个插件，才算是把这块逻辑彻底抽离出来了。它本质上是一个 Vue 的数字滚动组件，传入起始值和结束值，它负责在指定时间内把数字从起点平滑地"滚"到终点，支持自定义时长、缓动效果、小数位数、千分位分隔、前后缀等等。听起来功能不多，但每一个参数背后都对应着实际项目里踩过的坑。

这篇文章我打算把这个插件从里到外拆一遍。不是照搬官方文档那种"属性列表 + 示例"的写法，而是按照我自己的使用经验，讲清楚它解决了什么问题、内部大概是怎么实现的、每个参数在什么场景下该调、遇到问题怎么排查。如果你正在做数据可视化、后台看板、营销活动页，或者单纯想找一个靠谱的数字动画方案，这篇内容应该能帮你省下不少试错时间。即便你最后不用这个插件，里面关于数字动画的实现思路和避坑经验，自己手写的时候也用得上。

2. 先搞清楚它到底解决什么问题

2.1 数字滚动动画的常见实现方式对比

在聊vue-countTo之前，有必要先看看不用它的时候，大家一般怎么实现数字滚动。我把常见的几种方案列出来对比一下，这样你能更清楚这个插件的定位。

从表格能看出来，vue-countTo的定位很明确：它不试图做一个通用动画库，就专注把"数字从 A 滚到 B"这一件事做好。对于绝大多数业务场景来说，这个粒度刚刚好。你不需要为了一个看板数字去引入几百 KB 的动画库，也不用自己维护一套缓动和定时器逻辑。

2.2 它适合哪些场景，不适合哪些场景

先说适合的。后台数据看板是最典型的场景，一堆统计数字需要滚动展示；营销活动页面的中奖金额、累计参与人数，滚动起来更有冲击力；金融类应用里的账户余额、收益数字，滚动能体现"变化"的感觉；还有倒计时、进度百分比这类需要动态更新的数值展示。

再说不太适合的。如果你需要的是数字每一位单独滚动（类似老虎机那种效果），vue-countTo做不了，它整体是一个数值在变。如果你需要数字滚动的同时配合复杂的图形动画，那可能用 GSAP 这类库统一编排更合适。还有就是超高频更新的场景，比如每秒要变几十次的实时数据，滚动动画反而会拖累性能，这种情况直接显示数值更合理。

提示：判断要不要用滚动动画，一个简单的标准是——这个数字是不是"阶段性变化"的。如果是页面加载时展示一次、或者用户操作后变化一次，那用滚动动画很合适；如果是持续高频刷新的实时数据，就别加了。

2.3 为什么选择组件化而不是工具函数

这里有个设计上的选择值得说一下。数字滚动完全可以用一个工具函数实现，传入 DOM 元素和数值，函数内部去改textContent。但vue-countTo选择了组件化的路线，我认为这个选择是对的。

组件化的好处在于，它把"数值状态"和"视图更新"绑定在了一起。你用工具函数的话，得自己管理什么时候调用、调用时元素还在不在、组件销毁时要不要取消动画。而组件化之后，这些生命周期的事情框架帮你处理了，你只需要关心传进去的startVal和endVal。另外组件化天然支持响应式，endVal一变，动画自动重新触发，这在 Vue 的体系里用起来非常顺手。

3. 核心参数逐个拆解，每个都对应一个坑

3.1 startVal 与 endVal：动画的起点和终点

这两个参数是组件的核心。startVal是起始值，默认 0；endVal是结束值，必传。组件挂载后，会自动从startVal滚动到endVal。如果startVal大于endVal，它会反向滚动，这一点很多人不知道，但其实很实用——比如展示"下降了 300"这种场景，你就可以让起始值大于结束值。

这里有个细节要注意：endVal是响应式的。也就是说，当你在父组件里改变endVal的值时，组件会从当前显示的值重新滚动到新的endVal。这个特性在做动态数据更新时特别有用。比如用户切换了统计维度，数据从 1000 变成 5000，你只需要改endVal，动画会自动衔接，不用手动重置。

但这里也埋着一个坑：如果你在短时间内频繁修改endVal，比如接口轮询每秒返回一次新数据，那动画会不停地被打断重来，看起来就是数字一直在抖。这种情况要么加大轮询间隔，要么干脆关掉动画直接显示。

3.2 duration：滚动时长怎么定才不别扭

duration控制动画持续的时间，单位是毫秒，默认值是 2000，也就是 2 秒。这个默认值我觉得偏长了一点，实际项目里我一般会调到 1000 到 1500 之间。

时长这个东西很微妙。太短了，比如 300 毫秒，数字一闪而过，用户根本看不清滚动的过程，动画就失去了意义；太长了，比如 3 秒以上，用户盯着一个数字慢慢爬，会觉得很拖沓，尤其是页面上有十几个数字同时滚动的时候，等待感会很强。

我的经验是，单个数字的滚动控制在 1 到 1.5 秒比较舒服。如果是多个数字组成的看板，可以让它们的时长略有差异，形成一种错落的节奏感，但差异不要太大，否则会显得杂乱。另外，数值跨度大的时候可以适当延长时长，跨度小的时候缩短，这样视觉上的"速度感"会比较一致。

3.3 decimals：小数位数处理的那些事

decimals控制小数点后保留几位，默认是 0。这个参数看起来简单，但实际用起来问题不少。

首先是精度问题。JavaScript 的浮点数运算本身就存在精度误差，比如0.1 + 0.2不等于0.3。在滚动过程中，如果每一帧都用浮点数累加，最后显示的结果可能会出现123.45000000000001这种鬼东西。vue-countTo内部通过toFixed来处理显示，所以最终展示是干净的，但你在传endVal的时候，最好也确保传入的是一个合理精度的数值。

其次是小数位数的选择要和业务匹配。金额一般保留 2 位，百分比可能保留 1 位或 2 位，而像人数、订单数这种整数就不需要小数。如果你传了decimals: 2但endVal是整数，它会显示成1000.00，这个是否符合预期要看设计稿。

注意：decimals只影响显示，不影响内部计算。也就是说，即使你设置decimals: 0，内部滚动过程仍然是按浮点数走的，只是显示的时候四舍五入到整数。这会导致一个现象——滚动过程中数字可能看起来"跳"得不太均匀，因为小数部分被隐藏了。如果对滚动平滑度要求高，可以适当增加decimals。

3.4 separator：千分位分隔符的正确打开方式

separator用来设置千分位分隔符，默认是逗号。对于展示金额、人数这类大数字，千分位几乎是必须的，否则1234567这种数字读起来很费劲。

这个参数用起来没什么难度，但有个细节值得提：分隔符只在最终显示时生效，滚动过程中也是实时格式化的。这意味着如果数字从 999 滚到 1001，你会看到999变成1,000再变成1,001，分隔符是动态插入的，不会出现先显示1000再突然变成1,000的突兀感。

如果你不想要千分位，把separator设为空字符串就行。有些设计风格比较简洁，不喜欢逗号分隔，这时候就可以关掉。

3.5 prefix 与 suffix：前后缀的灵活运用

prefix和suffix分别是前缀和后缀，用来在数字前后拼接固定文本。最常见的用法是prefix: '¥'显示金额，或者suffix: '%'显示百分比。

这两个参数的价值在于，它让你不用在组件外面再包一层来加单位，数字和单位是一体的，滚动的时候单位不会跟着动，视觉上更稳定。如果单位放在外面，数字宽度变化的时候，单位的位置可能会跟着晃，体验不好。

有个小技巧：前缀后缀支持传入任意字符串，所以你可以用它来实现一些特殊效果，比如prefix: '共 '、suffix: ' 人参与'，把数字嵌在一句话中间。不过要注意，前缀后缀不参与动画，它们是静态显示的。

3.6 其他参数速览

除了上面几个核心参数，还有几个值得了解一下：

• autoplay：是否自动播放，默认true。设为false时组件不会自动开始滚动，需要你手动调用start()方法。这个在需要控制动画时机的场景下有用，比如等数据加载完再开始。
• useEasing：是否使用缓动效果，默认true。关掉之后就是匀速滚动，看起来会比较机械，一般不建议关。
• easingFn：自定义缓动函数，默认是easeOutExpo。如果你对动画曲线有特殊要求，可以传自己的函数进去。
• transition：Vue 2 版本里的过渡效果配置，Vue 3 版本里用法略有不同。

4. 内部实现原理，理解了才能用得明白

4.1 动画驱动：requestAnimationFrame 的妙用

vue-countTo内部用的是requestAnimationFrame来驱动动画，而不是setInterval。这个选择很关键，值得展开说说。

setInterval的问题是它不保证执行时机。你设定每 16 毫秒执行一次，但浏览器可能因为主线程忙而延迟执行，导致动画卡顿或者时间不准。而requestAnimationFrame是浏览器专门为动画提供的 API，它会在下一次重绘之前调用你的回调，天然与浏览器的刷新率同步。大多数显示器是 60Hz，也就是每秒 60 帧，requestAnimationFrame就会以大约 16.7 毫秒的间隔调用，动画看起来就很顺滑。

更重要的是，当页面切到后台标签页时，requestAnimationFrame会自动暂停，不消耗 CPU。而setInterval在后台仍然会执行，白白浪费资源。对于看板这类可能长时间开着的页面，这个差异很明显。

4.2 缓动函数：为什么数字滚动需要"减速"

默认的缓动函数是easeOutExpo，这是一个指数衰减的缓动。简单说，就是数字一开始滚得很快，然后越来越慢，最后缓缓停在终点。这种"快起慢停"的效果，符合人对物理运动的直觉——就像你推一个球，它一开始快，因为摩擦慢慢停下来。

如果不用缓动，数字匀速从 0 滚到 1000，看起来会很机械，像机器在计数而不是"数据在增长"。缓动函数的存在，让数字动画有了"生命感"。

easeOutExpo的数学表达式大概是这样的：

function easeOutExpo(t, b, c, d) { return c * (-Math.pow(2, -10 * t / d) + 1) + b; }

其中t是当前时间，b是起始值，c是变化量（结束值减起始值），d是总时长。这个函数的特点是前期变化快，后期变化慢，非常适合数字滚动。

如果你想换别的效果，可以自己实现缓动函数传进去。常见的还有easeOutQuad（二次衰减，比 Expo 温和）、easeInOutCubic（先加速后减速）等等。选择哪个取决于你想要的感觉，我一般用默认的就够了。

4.3 数值格式化：toFixed 与千分位的组合拳

滚动过程中，每一帧计算出的当前值都需要格式化后再显示。格式化的过程分两步：先按decimals保留小数位，再按separator插入千分位。

保留小数位用的是toFixed，这个方法会做四舍五入。这里有个细节：toFixed返回的是字符串，所以后续处理都是字符串操作。千分位的插入一般用正则表达式实现，类似这样：

function formatNumber(num, decimals, separator) { const fixed = Number(num).toFixed(decimals); const parts = fixed.split('.'); parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, separator); return parts.join('.'); }

这个正则\B(?=(\d{3})+(?!\d))的意思是：在非单词边界处，且后面跟着 3 的倍数个数字的位置，插入分隔符。这是千分位格式化的经典写法，理解了这个正则，你自己手写格式化也不成问题。

4.4 生命周期管理：组件销毁时发生了什么

组件化实现的一个关键优势就是生命周期管理。vue-countTo在组件销毁时会取消正在进行的requestAnimationFrame，避免回调继续执行导致报错或者内存泄漏。

如果你自己用setInterval手写，很容易忘记在beforeDestroy或onUnmounted里清理定时器。一旦组件销毁了但定时器还在跑，回调里访问已经销毁的 DOM 或者响应式数据，轻则报错，重则内存泄漏。这个插件帮你把这个坑填了。

另外，当endVal变化触发重新滚动时，它会先取消上一次的动画，再开始新的。这个"取消再开始"的逻辑很重要，否则多个动画同时跑，数字会乱跳。

5. 完整实操：从安装到跑起来

5.1 安装与引入

安装很简单，用 npm 或者 yarn 都行：

npm install vue-count-to --save

或者：

yarn add vue-count-to

引入方式分全局注册和局部注册两种。全局注册适合整个项目到处都要用的场景：

import Vue from 'vue'; import CountTo from 'vue-count-to'; Vue.component('CountTo', CountTo);

局部注册适合只在个别页面用，能减小打包体积：

import CountTo from 'vue-count-to'; export default { components: { CountTo } };

提示：如果你用的是 Vue 3，需要注意版本兼容性。vue-count-to早期版本主要面向 Vue 2，Vue 3 项目里可能需要找对应的兼容版本或者用@vue/compat过渡。安装前先确认一下你的 Vue 版本。

5.2 最简示例：让一个数字滚起来

先来个最简单的，从 0 滚到 1000：

<template> <div> <count-to :start-val="0" :end-val="1000" :duration="1500"></count-to> </div> </template> <script> import CountTo from 'vue-count-to'; export default { components: { CountTo } }; </script>

这段代码跑起来，你会看到数字从 0 快速滚动到 1000，大约 1.5 秒后停在 1000。这是最基础的用法，没有任何额外配置。

5.3 进阶示例：金额展示的完整配置

实际项目里，金额展示往往需要前缀、小数位、千分位都配上。假设要展示一笔 1,234,567.89 元的营收：

<template> <div class="revenue-card"> <count-to :start-val="0" :end-val="1234567.89" :duration="2000" :decimals="2" separator="," prefix="¥" ></count-to> </div> </template>

这样配置下来，数字会从¥0.00滚动到¥1,234,567.89，小数位固定 2 位，千分位用逗号分隔，前缀是人民币符号。滚动过程中，千分位和小数位都是实时格式化的，不会出现格式突变。

5.4 动态更新：响应式数据的处理

前面提到endVal是响应式的，这里给个实际例子。假设有一个按钮，点击后把数值从 1000 改成 5000：

<template> <div> <count-to :start-val="0" :end-val="currentValue" :duration="1200"></count-to> <button @click="updateValue">更新数据</button> </div> </template> <script> import CountTo from 'vue-count-to'; export default { components: { CountTo }, data() { return { currentValue: 1000 }; }, methods: { updateValue() { this.currentValue = 5000; } } }; </script>

点击按钮后，数字会从当前显示的值（1000）重新滚动到 5000。注意，它是从"当前值"开始滚，而不是从startVal重新开始，这个细节处理得很到位。

5.5 手动控制：autoplay 与 start 方法

有些场景下，你希望等数据加载完再开始动画，这时候可以把autoplay设为false，然后手动调用start()：

<template> <div> <count-to ref="countTo" :start-val="0" :end-val="dataFromApi" :autoplay="false" ></count-to> </div> </template> <script> export default { data() { return { dataFromApi: 0 }; }, async mounted() { const res = await fetchData(); this.dataFromApi = res.value; this.$nextTick(() => { this.$refs.countTo.start(); }); } }; </script>

这里用$nextTick是为了确保endVal更新后 DOM 已经重新渲染，再触发动画。如果不加$nextTick，可能会因为时序问题导致动画从旧值开始。

6. 踩坑实录与排查技巧

6.1 数字不滚动或者直接显示终值

这是最常见的问题，通常有几个原因。第一，endVal和startVal相等，那自然没什么可滚的，直接显示终值。第二，duration设成了 0，动画瞬间完成。第三，autoplay被设成了false但忘了调start()。第四，组件没有正确注册，Vue 把它当成了普通标签，自然不会有任何效果。

排查的时候，先打开控制台看看有没有报错，再检查一下传入的参数值。我遇到过一次是因为endVal传了个字符串"1000"而不是数字1000，虽然大部分情况下字符串也能工作，但某些版本下会导致计算异常。养成传数字类型的好习惯。

6.2 滚动过程中数字闪烁或跳动

数字闪烁通常和格式化有关。如果decimals设得太小，滚动过程中整数部分变化频繁，视觉上就会觉得数字在"跳"。解决办法是适当增加decimals，让小数位也参与滚动，视觉上会平滑很多。

另一个原因是duration太短。时间短意味着每帧变化的数值大，看起来就是大跳。把时长拉长到 1.5 秒以上，跳动感会明显减弱。

还有一种情况是多个数字组件同时滚动，如果它们的时长和缓动完全一样，会显得很整齐但也可能有点呆板；如果时长差异太大，又会显得杂乱。我的做法是让它们时长接近但略有差异，比如 1200、1300、1400 毫秒，形成自然的错落感。

6.3 页面切换后动画还在跑

这个问题一般出现在单页应用里。如果你在组件销毁时没有正确清理动画，切到别的路由后，requestAnimationFrame的回调可能还在执行，访问已经销毁的组件实例就会报错。

vue-countTo本身在beforeDestroy里做了清理，但如果你在父组件里手动调用了start()或者做了其他操作，可能会绕过它的清理逻辑。排查的时候，检查一下是否有在组件外部持有组件的引用，以及是否在destroyed之后还有代码在操作它。

6.4 常见问题速查表

6.5 几个我踩过的坑

第一个坑是关于decimals和endVal精度的配合。有一次我传了endVal: 99.999和decimals: 2，期望显示100.00，结果滚动过程中显示的是99.99然后突然跳到100.00，因为toFixed的四舍五入是在最后一步做的。后来我把endVal直接改成100，问题就没了。教训是：传入的endVal精度最好和decimals匹配，不要指望组件帮你做复杂的精度转换。

第二个坑是关于多个组件同时滚动的性能。有一次一个看板页面放了 20 多个count-to组件，每个都在跑requestAnimationFrame，结果页面明显卡顿。后来我做了优化：把不在一屏内的组件用autoplay: false延迟启动，等滚动到可视区域再触发。这个优化思路对所有动画组件都适用。

第三个坑是关于prefix和suffix的样式。前缀后缀是直接拼在数字旁边的，如果你想让它们和数字有不同的颜色或字号，需要额外用 CSS 处理。我一般的做法是给组件外层包一个容器，然后用::first-letter或者包裹span来单独设置样式。不过更简单的办法是干脆不用prefix，在组件外面自己拼，这样样式控制更灵活。

7. 和其他方案的对比与选型建议

7.1 与手写实现的对比

手写数字滚动最大的优势是可控性，你可以完全按照自己的需求定制每一个细节。但代价是代码量和维护成本。一个健壮的手写实现，需要考虑缓动函数、时间计算、格式化、生命周期清理、响应式更新等等，写下来少说也有一两百行。而vue-count-to把这些都封装好了，你只需要传几个参数。

从维护角度看，第三方插件有社区维护，遇到 bug 会有人修，而手写代码出了问题只能自己扛。当然，前提是这个插件还在活跃维护。选型的时候可以看一下它的更新频率和 issue 处理情况。

7.2 与通用动画库的对比

像 GSAP 这样的通用动画库，功能远比vue-count-to强大，它能做数字滚动，也能做位移、缩放、旋转、时间轴编排等等。如果你的项目里已经有 GSAP，那用它来做数字滚动也完全可以，没必要再引入一个专门的插件。

但如果你的项目里只有数字滚动这一个动画需求，为了它引入一个几百 KB 的动画库就不划算了。vue-count-to的体积很小，压缩后只有几 KB，对于只做数字滚动的场景，它是更轻量的选择。

7.3 什么情况下建议自己实现

虽然我推荐vue-count-to，但有两种情况我会建议自己实现。一是你的需求非常特殊，比如数字每一位单独滚动、或者滚动过程中要配合其他复杂动画，这种定制化需求插件满足不了。二是你的项目对第三方依赖有严格限制，比如某些企业内网项目不允许引入外部包，那就只能自己写。

自己实现的时候，核心就是requestAnimationFrame加缓动函数，再配合格式化逻辑。前面讲的原理部分已经把这几个关键点都覆盖了，照着思路写一个可用的版本并不难。

8. 一些延伸玩法和优化思路

8.1 结合 Intersection Observer 做懒启动

前面提到多个组件同时滚动会卡顿，解决办法之一是懒启动。用Intersection Observer监听组件是否进入可视区域，进入后再把autoplay设为true或者调用start()。这样首屏只启动可见的几个动画，性能压力小很多。

const observer = new IntersectionObserver((entries) => { entries.forEach(entry => { if (entry.isIntersecting) { entry.target.__vue__.start(); observer.unobserve(entry.target); } }); });

这段代码只是示意，实际用的时候要结合组件的 ref 来操作。核心思路就是"可见才动"，这个优化对长页面的看板特别有效。

8.2 用 CSS 变量控制样式

count-to渲染出来的就是一个普通的文本节点，你可以用 CSS 自由控制它的字体、颜色、大小。如果想让数字用等宽字体避免滚动时宽度跳动，可以设置font-variant-numeric: tabular-nums，这个 CSS 属性会让数字等宽显示，滚动时不会因为数字宽度不同而左右晃动。

.count-to-wrapper { font-variant-numeric: tabular-nums; font-feature-settings: "tnum"; }

这个小技巧对金额展示尤其重要，否则1和8宽度不同，滚动时整个数字会左右抖。

8.3 数字变化时的视觉反馈

单纯的数字滚动有时候不够醒目，可以配合颜色变化或者缩放动画。比如数字滚动时颜色从灰色渐变到高亮色，或者结束时有一个轻微的放大回弹。这些效果用 CSS transition 配合 Vue 的 class 绑定就能实现，不需要额外的动画库。

我的做法是给组件外层加一个 class，在endVal变化时切换这个 class，触发 CSS 动画。等动画结束后再移除 class。这样数字滚动和视觉反馈是联动的，体验会更好。

8.4 服务端渲染的注意事项

如果你的项目用了服务端渲染，vue-count-to可能会有问题，因为requestAnimationFrame是浏览器 API，服务端没有。这种情况下，需要确保组件只在客户端激活动画，服务端渲染时直接输出终值。一般通过process.client或者mounted钩子来判断环境。

这个点比较小众，但如果你的项目是 Nuxt 这类框架，就需要注意。解决办法也不复杂，把动画逻辑放在mounted里，服务端渲染时组件显示静态值，客户端接管后再开始滚动。

9. 关于版本兼容和迁移的碎碎念

vue-count-to最初是为 Vue 2 写的，随着 Vue 3 的普及，很多人在迁移时会遇到问题。Vue 3 的组件注册方式、生命周期钩子名称、响应式 API 都有变化，直接拿 Vue 2 的用法在 Vue 3 里跑可能会报错。

如果你在 Vue 3 项目里用，有几个选择：一是找社区维护的 Vue 3 兼容版本；二是用@vue/compat兼容模式；三是干脆自己照着原理实现一个 Vue 3 版本。自己实现的话，把beforeDestroy换成onUnmounted，把this.$refs换成ref，核心逻辑基本不用动。

我在 Vue 3 项目里是自己封装了一个组合式函数，把数字滚动的逻辑抽出来，用起来比组件更灵活。核心就是一个ref存当前显示值，一个requestAnimationFrame循环更新这个ref，模板里直接绑定。这样既复用了逻辑，又不受组件版本的限制。

10. 最后聊几句实际使用的心得

用了这么久vue-count-to，我最大的感受是：它把一件小事做得很扎实。数字滚动这个需求，看起来简单，但要做好并不容易，涉及动画、格式化、生命周期、响应式等多个方面。这个插件没有追求大而全，就专注把这一件事做好，参数设计也基本覆盖了实际场景的需要。

如果你正在做数据看板或者营销页面，需要数字滚动效果，我建议先试试它。大部分情况下，默认配置加上几个参数调整就能满足需求。如果遇到它搞不定的特殊需求，再考虑自己实现或者换更重的方案。

选型的时候不要只看功能列表，还要看它的维护状态、体积、和你项目的技术栈是否匹配。一个再好的插件，如果和你的技术栈不兼容，用起来也是折磨。反过来，一个简单的插件，只要用对了地方，就能省下大量时间。

数字滚动这件事，说到底是为了让数据展示更有"感觉"。用户看到数字滚动，会下意识觉得数据是"活"的、"实时"的，这种心理暗示对产品体验是有加分的。但也要克制，不是所有数字都需要滚动，用多了反而显得花哨。什么时候用、怎么用，还是要回到业务场景本身去判断。