1. 数字滚动这件小事为什么值得单独拎出来说做前端这些年有一个需求出现的频率高得离谱但每次实现起来又总觉得差点意思——数字滚动动画。比如后台管理系统的数据看板一打开页面总营业额从 0 一路跳到 128,456比如活动页面的倒计时或者中奖金额展示数字得有个滚动的过程直接静态显示总觉得少了点仪式感。这个需求看起来简单但真动手写的时候你会发现要考虑的东西比想象中多缓动函数怎么选、小数位怎么处理、千分位分隔符怎么加、滚动过程中数字跳动会不会闪、组件卸载时定时器怎么清理……我最早接触这类需求的时候也是手写requestAnimationFrame配合setInterval硬撸结果就是每个项目都要复制一遍类似的代码改起来还容易漏掉边界情况。后来用上了vue-countTo这个插件才算是把这块逻辑彻底抽离出来了。它本质上是一个 Vue 的数字滚动组件传入起始值和结束值它负责在指定时间内把数字从起点平滑地滚到终点支持自定义时长、缓动效果、小数位数、千分位分隔、前后缀等等。听起来功能不多但每一个参数背后都对应着实际项目里踩过的坑。这篇文章我打算把这个插件从里到外拆一遍。不是照搬官方文档那种属性列表 示例的写法而是按照我自己的使用经验讲清楚它解决了什么问题、内部大概是怎么实现的、每个参数在什么场景下该调、遇到问题怎么排查。如果你正在做数据可视化、后台看板、营销活动页或者单纯想找一个靠谱的数字动画方案这篇内容应该能帮你省下不少试错时间。即便你最后不用这个插件里面关于数字动画的实现思路和避坑经验自己手写的时候也用得上。2. 先搞清楚它到底解决什么问题2.1 数字滚动动画的常见实现方式对比在聊vue-countTo之前有必要先看看不用它的时候大家一般怎么实现数字滚动。我把常见的几种方案列出来对比一下这样你能更清楚这个插件的定位。实现方式核心思路优点缺点CSS 动画 计数器用keyframes配合counter-reset纯 CSS性能好无法精确控制结束值兼容性差小数和千分位难处理手写setInterval定时器每隔几十毫秒加一点实现简单容易理解时间不精确容易掉帧卸载时忘记清理会内存泄漏手写requestAnimationFrame按帧刷新配合缓动函数流畅与浏览器刷新同步代码量大缓动函数、边界处理都要自己写第三方动画库如 GSAP用成熟动画库驱动数值功能强大缓动丰富体积大为一个数字动画引入整个库不划算vue-countTo封装好的 Vue 组件开箱即用参数齐全体积小只专注数字滚动这一件事从表格能看出来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是起始值默认 0endVal是结束值必传。组件挂载后会自动从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。如果你对动画曲线有特殊要求可以传自己的函数进去。transitionVue 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 2Vue 3 项目里可能需要找对应的兼容版本或者用vue/compat过渡。安装前先确认一下你的 Vue 版本。5.2 最简示例让一个数字滚起来先来个最简单的从 0 滚到 1000template div count-to :start-val0 :end-val1000 :duration1500/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 classrevenue-card count-to :start-val0 :end-val1234567.89 :duration2000 :decimals2 separator, prefix¥ /count-to /div /template这样配置下来数字会从¥0.00滚动到¥1,234,567.89小数位固定 2 位千分位用逗号分隔前缀是人民币符号。滚动过程中千分位和小数位都是实时格式化的不会出现格式突变。5.4 动态更新响应式数据的处理前面提到endVal是响应式的这里给个实际例子。假设有一个按钮点击后把数值从 1000 改成 5000template div count-to :start-val0 :end-valcurrentValue :duration1200/count-to button clickupdateValue更新数据/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 refcountTo :start-val0 :end-valdataFromApi :autoplayfalse /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 常见问题速查表问题现象可能原因解决办法数字不滚动endVal 等于 startVal检查两个值是否不同数字不滚动autoplay 为 false手动调用 start() 方法数字不滚动组件未注册检查 components 注册直接显示终值duration 为 0设置合理的时长数字闪烁跳动decimals 太小增加小数位数数字闪烁跳动duration 太短延长动画时长切换页面后报错动画未清理检查组件销毁逻辑格式显示异常separator 配置错误检查分隔符设置小数精度异常浮点数误差用 toFixed 处理显示动态更新不生效endVal 非响应式确保数据是响应式的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我最大的感受是它把一件小事做得很扎实。数字滚动这个需求看起来简单但要做好并不容易涉及动画、格式化、生命周期、响应式等多个方面。这个插件没有追求大而全就专注把这一件事做好参数设计也基本覆盖了实际场景的需要。如果你正在做数据看板或者营销页面需要数字滚动效果我建议先试试它。大部分情况下默认配置加上几个参数调整就能满足需求。如果遇到它搞不定的特殊需求再考虑自己实现或者换更重的方案。选型的时候不要只看功能列表还要看它的维护状态、体积、和你项目的技术栈是否匹配。一个再好的插件如果和你的技术栈不兼容用起来也是折磨。反过来一个简单的插件只要用对了地方就能省下大量时间。数字滚动这件事说到底是为了让数据展示更有感觉。用户看到数字滚动会下意识觉得数据是活的、实时的这种心理暗示对产品体验是有加分的。但也要克制不是所有数字都需要滚动用多了反而显得花哨。什么时候用、怎么用还是要回到业务场景本身去判断。