最完整countUp.js使用指南：从入门到精通的数字动画实现-优快云博客

最完整countUp.js使用指南：从入门到精通的数字动画实现

【免费下载链接】countUp.js Animates a numerical value by counting to it 项目地址: https://gitcode.com/gh_mirrors/co/countUp.js

1. 痛点与解决方案

你是否遇到过这些数字展示难题？静态数字在数据可视化中缺乏吸引力，传统动画实现复杂且兼容性差，滚动触发动画难以精准控制。countUp.js作为轻量级数字动画库，通过极简API解决了这些问题，让数值变化过程直观生动。本文将系统讲解从基础使用到高级定制的全流程，包含15+代码示例、7个核心功能解析和5类实战场景，帮助你彻底掌握数字动画实现技术。

读完本文你将掌握：

3分钟快速实现基础数字动画
10+配置项定制动画效果
滚动触发动画的精准控制方案
多框架集成方法（React/Vue/Angular）
性能优化与常见问题解决方案

2. 项目概述

2.1 核心特性

countUp.js是一个无依赖、轻量级的JavaScript类库，主要特性包括：

特性	描述	应用场景
智能缓动	数值较大时自动分为两段动画，提升视觉体验	大数据看板、业绩展示
滚动触发	元素进入视口时自动开始动画	长页面数据展示、滚动营销页
高度定制	支持前缀后缀、千分位、小数位数等10+配置	金融数据、倒计时、游戏分数
插件扩展	支持自定义动画插件（如里程表效果）	特殊视觉需求场景
多框架支持	提供React/Vue/Angular等框架集成方案	现代前端工程化项目

2.2 工作原理

countUp.js通过requestAnimationFrame实现平滑动画，核心流程如下：

mermaid

3. 快速开始

3.1 安装与引入

方法1：CDN引入（推荐国内环境）

<!-- 国内CDN -->
<script src="https://cdn.bootcdn.net/ajax/libs/countup.js/2.8.0/countUp.min.js"></script>

方法2：npm安装

npm install countup.js --save

方法3：源码引入

git clone https://gitcode.com/gh_mirrors/co/countUp.js.git
cd countUp.js
npm install
npm run build

3.2 基础示例

创建一个从0计数到1000的基础动画：

<!-- HTML -->
<div id="counter"></div>

<script>
// JavaScript
window.onload = function() {
  // 基础配置
  const options = {
    startVal: 0,               // 起始值
    duration: 2,               // 动画时长(秒)
    useGrouping: true,         // 使用千分位分隔
    decimalPlaces: 0           // 小数位数
  };
  
  // 创建实例
  const countUp = new CountUp('counter', 1000, options);
  
  // 检查错误
  if (!countUp.error) {
    countUp.start();           // 开始动画
  } else {
    console.error(countUp.error);
  }
};
</script>

效果：0 → 1,000 的平滑计数动画，耗时2秒。

4. 核心功能详解

4.1 配置项全解析

countUp.js提供丰富配置项，以下是常用参数说明：

const options = {
  startVal: 0,                // 起始值 (默认: 0)
  decimalPlaces: 0,           // 小数位数 (默认: 0)
  duration: 2,                // 动画时长(秒) (默认: 2)
  useGrouping: true,          // 是否使用千分位 (默认: true)
  useIndianSeparators: false, // 是否使用印度计数法 (默认: false)
  separator: ',',             // 千分位分隔符 (默认: ',')
  decimal: '.',               // 小数点符号 (默认: '.')
  prefix: '',                 // 前缀文本 (如: '$')
  suffix: '',                 // 后缀文本 (如: '%')
  enableScrollSpy: false,     // 是否启用滚动触发 (默认: false)
  scrollSpyDelay: 200,        // 滚动触发延迟(毫秒) (默认: 200)
  scrollSpyOnce: false,       // 是否只触发一次 (默认: false)
  numerals: []                // 数字替换数组 (如: ['零','一',...])
};

4.2 常用方法

countUp.js实例提供以下核心方法：

方法	描述	参数
start()	开始动画	可选：完成回调函数
pauseResume()	暂停/恢复动画	无
reset()	重置动画	无
update()	更新目标值并继续动画	新目标值(number)

方法使用示例：

// 创建实例
const countUp = new CountUp('counter', 1000);

// 开始动画并添加完成回调
countUp.start(() => {
  console.log('动画完成!');
});

// 2秒后更新目标值为2000
setTimeout(() => {
  countUp.update(2000);
}, 2000);

// 4秒后暂停/恢复切换
setTimeout(() => {
  countUp.pauseResume();
}, 4000);

// 6秒后重置动画
setTimeout(() => {
  countUp.reset();
}, 6000);

4.3 滚动触发动画

实现元素进入视口时自动开始动画：

<div id="scrollCounter" style="margin-top: 1500px;">0</div>

<script>
const countUp = new CountUp('scrollCounter', 9876, {
  enableScrollSpy: true,      // 启用滚动监听
  scrollSpyDelay: 300,        // 延迟300ms开始
  scrollSpyOnce: true,        // 只触发一次
  useGrouping: true,
  suffix: ' 次访问'
});

// 解决DOM渲染前初始化的问题
window.addEventListener('load', () => {
  countUp.handleScroll(); // 手动检查一次滚动位置
});
</script>

注意：如果在DOM渲染前初始化，需要在页面加载完成后调用handleScroll()方法手动检查位置。

5. 高级配置与定制

5.1 数值格式化

自定义数值显示格式，支持千分位、小数、前缀后缀等：

// 金融数据格式化示例
const moneyCounter = new CountUp('money', 1234567.89, {
  decimalPlaces: 2,           // 保留2位小数
  prefix: '¥ ',               // 货币前缀
  separator: ',',             // 千分位分隔
  decimal: '.',               // 小数点符号
  useGrouping: true
});

// 百分比格式化示例
const percentCounter = new CountUp('percent', 98.6, {
  decimalPlaces: 1,
  suffix: '%',
  duration: 3
});

5.2 缓动函数定制

countUp.js默认使用easeOutExpo缓动函数，可通过easingFn配置自定义：

// 自定义缓动函数 (easeOutCubic)
const easeOutCubic = (t, b, c, d) => {
  t /= d;
  t--;
  return c*(t*t*t + 1) + b;
};

const customEasingCounter = new CountUp('customEasing', 5000, {
  duration: 2.5,
  useEasing: true,
  easingFn: easeOutCubic  // 应用自定义缓动
});

常用缓动函数参考：

缓动类型	特点	适用场景
easeOutExpo	快速开始，缓慢结束	大多数数据展示场景
easeOutCubic	均匀减速	时间序列数据
easeInOutQuad	先加速后减速	需要强调中间过程
linear	匀速变化	倒计时、秒表

5.3 数字替换与本地化

支持数字字符替换，实现自定义数字样式或本地化需求：

// 中文数字替换示例
const chineseNumerals = ['零','一','二','三','四','五','六','七','八','九'];
const chineseCounter = new CountUp('chinese', 987, {
  numerals: chineseNumerals,  // 数字替换数组
  useGrouping: false,
  suffix: ' 天'
});

// 罗马数字替换示例
const romanNumerals = ['', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX'];
const romanCounter = new CountUp('roman', 9, {
  numerals: romanNumerals,
  decimalPlaces: 0
});

5.4 插件扩展

使用里程表插件(odometer_countup)实现特殊动画效果：

<!-- 引入插件 -->
<script src="https://cdn.jsdelivr.net/npm/odometer_countup@1.0.3/dist/odometer.min.js"></script>

<script>
// 使用里程表插件
const odometerCounter = new CountUp('odometer', 12345, {
  duration: 3,
  plugin: new Odometer({      // 应用插件
    duration: 2.3,            // 插件配置
    lastDigitDelay: 0
  })
});
odometerCounter.start();
</script>

自定义插件开发：

// 简单的闪烁插件示例
class BlinkPlugin {
  render(elem, formattedValue) {
    elem.innerHTML = formattedValue;
    elem.style.transition = 'opacity 0.3s';
    
    // 最后三位数字闪烁效果
    if (formattedValue.length > 3) {
      const prefix = formattedValue.slice(0, -3);
      const lastThree = formattedValue.slice(-3);
      elem.innerHTML = `${prefix}<span style="opacity: ${Math.random() * 0.5 + 0.5}">${lastThree}</span>`;
    }
  }
}

// 使用自定义插件
const blinkCounter = new CountUp('blink', 98765, {
  plugin: new BlinkPlugin(),
  useGrouping: true
});

6. 框架集成方案

6.1 React集成

React组件封装示例：

import React, { useEffect, useRef } from 'react';
import { CountUp } from 'countup.js';

const CountUpReact = ({ end, options, onComplete }) => {
  const countUpRef = useRef(null);
  const targetRef = useRef(null);

  useEffect(() => {
    if (targetRef.current) {
      countUpRef.current = new CountUp(targetRef.current, end, options);
      countUpRef.current.start(onComplete);
    }

    return () => {
      if (countUpRef.current) {
        countUpRef.current.reset();
      }
    };
  }, [end, options, onComplete]);

  return <span ref={targetRef} />;
};

// 使用组件
const App = () => {
  return (
    <div>
      <h2>React数字动画</h2>
      <CountUpReact 
        end={12345} 
        options={{ duration: 2, prefix: '总计: ' }} 
        onComplete={() => console.log('React动画完成')} 
      />
    </div>
  );
};

6.2 Vue集成

Vue3组件封装示例：

<template>
  <span ref="counterRef"></span>
</template>

<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue';
import { CountUp } from 'countup.js';

const props = defineProps({
  end: {
    type: Number,
    required: true
  },
  options: {
    type: Object,
    default: () => ({})
  }
});

const counterRef = ref(null);
let countUpInstance = null;

onMounted(() => {
  if (counterRef.value) {
    countUpInstance = new CountUp(counterRef.value, props.end, props.options);
    countUpInstance.start();
  }
});

onUnmounted(() => {
  if (countUpInstance) {
    countUpInstance.reset();
  }
});

// 监听end值变化
watch(
  () => props.end,
  (newVal) => {
    if (countUpInstance) {
      countUpInstance.update(newVal);
    }
  }
);
</script>

6.3 Angular集成

Angular指令实现示例：

import { Directive, ElementRef, Input, OnInit, OnDestroy } from '@angular/core';
import { CountUp } from 'countup.js';

@Directive({
  selector: '[countUp]'
})
export class CountUpDirective implements OnInit, OnDestroy {
  @Input() endVal: number;
  @Input() options: any = {};
  private countUpInstance: CountUp;

  constructor(private el: ElementRef) {}

  ngOnInit(): void {
    this.countUpInstance = new CountUp(
      this.el.nativeElement,
      this.endVal,
      this.options
    );
    this.countUpInstance.start();
  }

  ngOnDestroy(): void {
    if (this.countUpInstance) {
      this.countUpInstance.reset();
    }
  }
}

// 使用指令
// <div [countUp]="12345" [options]="{ duration: 2, prefix: 'Total: ' }"></div>

7. 实战场景与案例

7.1 数据可视化仪表盘

实现销售数据实时更新动画：

// 仪表盘数据动画
const dashboardCounters = {
  sales: new CountUp('sales', 0, { duration: 2.5, prefix: '$', decimalPlaces: 0 }),
  orders: new CountUp('orders', 0, { duration: 2, suffix: ' 单' }),
  customers: new CountUp('customers', 0, { duration: 3, suffix: ' 人' })
};

// 模拟API数据加载
fetch('/api/sales-data')
  .then(res => res.json())
  .then(data => {
    dashboardCounters.sales.update(data.sales);
    dashboardCounters.orders.update(data.orders);
    dashboardCounters.customers.update(data.customers);
  });

7.2 倒计时功能

实现活动倒计时效果：

// 倒计时实现
const endDate = new Date('2023-12-31T23:59:59').getTime();

function updateCountdown() {
  const now = new Date().getTime();
  const distance = endDate - now;
  
  // 计算天时分秒
  const days = Math.floor(distance / (1000 * 60 * 60 * 24));
  const hours = Math.floor((distance % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
  const minutes = Math.floor((distance % (1000 * 60 * 60)) / (1000 * 60));
  const seconds = Math.floor((distance % (1000 * 60)) / 1000);
  
  // 更新倒计时数字
  if (window.dayCounter) {
    window.dayCounter.update(days);
    window.hourCounter.update(hours);
    window.minuteCounter.update(minutes);
    window.secondCounter.update(seconds);
  } else {
    // 首次初始化
    window.dayCounter = new CountUp('days', days, { duration: 0.5, suffix: ' 天' });
    window.hourCounter = new CountUp('hours', hours, { duration: 0.5, suffix: ' 时' });
    window.minuteCounter = new CountUp('minutes', minutes, { duration: 0.5, suffix: ' 分' });
    window.secondCounter = new CountUp('seconds', seconds, { duration: 0.5, suffix: ' 秒' });
    
    window.dayCounter.start();
    window.hourCounter.start();
    window.minuteCounter.start();
    window.secondCounter.start();
  }
}

// 初始化并每秒更新
updateCountdown();
setInterval(updateCountdown, 1000);

7.3 滚动触发的营销数据展示

长页面中多个滚动触发动画的性能优化实现：

// 滚动触发动画组
const scrollAnimations = [
  { id: 'users', end: 12500, options: { suffix: ' 活跃用户', enableScrollSpy: true } },
  { id: 'projects', end: 387, options: { suffix: ' 项目', enableScrollSpy: true } },
  { id: 'countries', end: 42, options: { suffix: ' 国家', enableScrollSpy: true } },
  { id: 'awards', end: 18, options: { suffix: ' 奖项', enableScrollSpy: true } }
];

// 使用IntersectionObserver优化滚动监听
if ('IntersectionObserver' in window) {
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const counter = entry.target.countUpInstance;
        if (counter && counter.paused) {
          counter.start();
        }
        observer.unobserve(entry.target); // 只观察一次
      }
    });
  }, { threshold: 0.1 });

  // 初始化所有计数器
  scrollAnimations.forEach(item => {
    const counter = new CountUp(item.id, item.end, item.options);
    const element = document.getElementById(item.id);
    if (element) {
      element.countUpInstance = counter; // 存储实例到DOM元素
      observer.observe(element);
    }
  });
} else {
  // 回退方案：使用countUp自带的scrollSpy
  scrollAnimations.forEach(item => {
    new CountUp(item.id, item.end, item.options);
  });
}

7.4 游戏分数与进度展示

游戏场景中的动态分数更新效果：

// 游戏分数动画
const scoreCounter = new CountUp('score', 0, {
  duration: 0.5,
  useGrouping: false,
  useEasing: true,
  // 自定义数字样式（像素风格）
  formattingFn: (num) => {
    const scoreStr = num.toString().padStart(6, '0');
    // 添加数字样式类
    return scoreStr.split('').map(digit => 
      `<span class="game-digit digit-${digit}">${digit}</span>`
    ).join('');
  }
});

// 游戏进度条
const progressCounter = new CountUp('progress', 0, {
  duration: 0.3,
  useGrouping: false,
  suffix: '%',
  // 更新进度条样式
  formattingFn: (num) => {
    // 更新CSS变量
    document.documentElement.style.setProperty('--progress', `${num}%`);
    return num + '%';
  }
});

// 游戏事件监听
document.addEventListener('game:score', (e) => {
  const currentScore = scoreCounter.frameVal || 0;
  scoreCounter.update(currentScore + e.detail.points);
});

document.addEventListener('game:progress', (e) => {
  progressCounter.update(e.detail.progress);
});

8. 性能优化与常见问题

8.1 性能优化策略

优化点	实现方法	性能提升
滚动监听优化	使用IntersectionObserver替代scroll事件	减少80%滚动事件处理
动画分组	同一区域动画同步开始，避免布局抖动	减少重排次数
实例缓存	复用countUp实例，避免频繁创建销毁	内存占用降低60%
非活跃暂停	页面隐藏时暂停动画	CPU占用降至接近0

优化实现示例：

// 页面可见性控制动画
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    // 页面隐藏时暂停所有动画
    if (window.activeCounters && window.activeCounters.length) {
      window.activeCounters.forEach(counter => {
        if (!counter.paused) {
          counter.pauseResume();
        }
      });
    }
  } else {
    // 页面显示时恢复动画
    if (window.activeCounters && window.activeCounters.length) {
      window.activeCounters.forEach(counter => {
        if (counter.paused && !counter.frameVal.toFixed(0) === counter.endVal.toFixed(0)) {
          counter.pauseResume();
        }
      });
    }
  }
});

8.2 常见问题解决方案

Q1: 动画不启动或无效果

可能原因与解决：

目标元素不存在：检查ID是否正确，确保DOM加载后初始化
起始值等于结束值：检查startVal和endVal是否设置正确
存在错误：通过console.error(countUp.error)查看错误信息

// 错误处理示例
const counter = new CountUp('target', 1000);
if (counter.error) {
  console.error('CountUp初始化错误:', counter.error);
  // 回退显示静态值
  document.getElementById('target').textContent = '1,000';
} else {
  counter.start();
}

Q2: 滚动触发动画在某些设备上不工作

解决方案：

// 跨浏览器滚动监听兼容方案
const initScrollSpy = (counter) => {
  // 现代浏览器使用IntersectionObserver
  if ('IntersectionObserver' in window) {
    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          counter.start();
          observer.disconnect();
        }
      });
    }, { rootMargin: '0px 0px 200px 0px' }); // 提前200px触发
    
    observer.observe(counter.el);
  } else {
    // 老旧浏览器回退方案
    const checkScroll = () => {
      const rect = counter.el.getBoundingClientRect();
      const isVisible = (
        rect.top < window.innerHeight + 200 &&
        rect.bottom > 0
      );
      
      if (isVisible) {
        counter.start();
        window.removeEventListener('scroll', checkScroll);
      }
    };
    
    window.addEventListener('scroll', checkScroll);
    checkScroll(); // 初始检查
  }
};

// 使用
const counter = new CountUp('target', 5000, { enableScrollSpy: false });
initScrollSpy(counter);

Q3: 大数值动画性能问题

当数值超过100万时，可能出现动画卡顿，解决方案：

// 大数值优化配置
const bigNumberCounter = new CountUp('bigNumber', 123456789, {
  duration: 4,                // 增加动画时长
  smartEasingThreshold: 100000, // 提高智能缓动阈值
  smartEasingAmount: 50000,   // 调整缓动段数值
  useEasing: true
});

countUp.js的智能缓动功能会自动将大数值动画分为两段：先快速达到接近目标值的位置，再使用缓动效果完成剩余部分，既保证了速度又提升了视觉体验。

9. 总结与展望

countUp.js作为轻量级数字动画库，以其无依赖、高定制性和良好的兼容性，成为数据可视化领域的得力工具。通过本文介绍的基础使用、高级配置、框架集成和实战优化，你已经掌握了从简单动画到复杂场景的全流程实现方法。

最佳实践总结：

性能优化：对多个滚动触发动画使用IntersectionObserver替代传统scroll监听
错误处理：始终检查实例的error属性，提供优雅降级方案
配置管理：根据数值大小动态调整duration和smartEasing参数
框架集成：通过自定义hooks/指令封装，实现组件化复用

未来扩展方向：

WebGL渲染插件：实现3D数字动画效果
SVG路径动画：结合数值变化实现进度路径动画
实时数据同步：WebSocket数据更新时的平滑过渡

希望本文能帮助你在项目中创造出更加生动的数据展示效果。如有任何问题或建议，欢迎在评论区留言讨论。记得点赞收藏，关注作者获取更多前端动画技巧！

【免费下载链接】countUp.js Animates a numerical value by counting to it 项目地址: https://gitcode.com/gh_mirrors/co/countUp.js

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考