README

CountUp.js 是一个无需依赖的轻量级 JavaScript 类，可以快速创建以更吸引人的方式显示数值数据的动画。

尽管其名称为 CountUp，但它可以根据您传递的起始和结束值以任意方向计数。

CountUp.js 支持 所有浏览器。MIT 许可证。

尝试演示

或在 Stackblitz 中对 CountUp 进行实验

跳转到

• 用法
• 包含 CountUp
• 贡献
• 创建动画插件

特性

• 当元素滚动到视图中时动画。 使用选项 enableScrollSpy。
• 高度可定制，具有大量选项，您甚至可以替换数字。
• 智能缓动：CountUp 智能地延迟缓动，直到接近结束值，缓动对视觉明显为止。在 选项 中可配置。
• 插件 允许使用替代动画，如 Odometer 插件

用法

CountUp 可以与以下工具一起使用

• Angular 2+
• Angular 1.x
• React
• Svelte
• Vue
• WordPress
• jQuery

直接使用 CountUp

在 npm 上作为 countup.js。您可以将其作为模块导入，或包含 UMD 脚本并全局访问 CountUp。有关包含 CountUp 的详细信息，请参阅 详细说明。

参数:

• target: string | HTMLElement | HTMLInputElement - 发生计数的 HTML 元素、输入、SVG 文本元素或 DOM 元素引用的 ID
• endVal: number - 您想要到达的值
• options?: CountUpOptions - 用于细粒度控制的可选配置对象

选项（默认值）：

interface CountUpOptions {
  startVal?: number; // number to start at (0)
  decimalPlaces?: number; // number of decimal places (0)
  duration?: number; // animation duration in seconds (2)
  useGrouping?: boolean; // example: 1,000 vs 1000 (true)
  useIndianSeparators?: boolean; // example: 1,00,000 vs 100,000 (false)
  useEasing?: boolean; // ease animation (true)
  smartEasingThreshold?: number; // smooth easing for large numbers above this if useEasing (999)
  smartEasingAmount?: number; // amount to be eased for numbers above threshold (333)
  separator?: string; // grouping separator (',')
  decimal?: string; // decimal ('.')
  // easingFn: easing function for animation (easeOutExpo)
  easingFn?: (t: number, b: number, c: number, d: number) => number;
  formattingFn?: (n: number) => string; // this function formats result
  prefix?: string; // text prepended to result
  suffix?: string; // text appended to result
  numerals?: string[]; // numeral glyph substitution
  enableScrollSpy?: boolean; // start animation when target is in view
  scrollSpyDelay?: number; // delay (ms) after target comes into view
  scrollSpyOnce?: boolean; // run only once
  onCompleteCallback?: () => any; // gets called when animation completes
  onStartCallback?: () => any; // gets called when animation starts
  plugin?: CountUpPlugin; // for alternate animations
}

示例用法:

const countUp = new CountUp('targetId', 5234);
if (!countUp.error) {
  countUp.start();
} else {
  console.error(countUp.error);
}

传递选项

const countUp = new CountUp('targetId', 5234, options);

带有可选的完成回调

const countUp = new CountUp('targetId', 5234, { onCompleteCallback: someMethod });

// or (passing fn to start will override options.onCompleteCallback)
countUp.start(someMethod);

// or
countUp.start(() => console.log('Complete!'));

其他方法:

切换暂停/继续

countUp.pauseResume();

重置动画

countUp.reset();

更新结束值并动画化

countUp.update(989);

当元素滚动到视图中时动画

使用滚动间谍选项在元素滚动到视图中时动画。当使用滚动间谍时，只需初始化 CountUp 但不要调用 start();

const countUp = new CountUp('targetId', 989, { enableScrollSpy: true });

滚动间谍故障排除

CountUp 初始化后会立即检查滚动位置。因此，如果您在 DOM 渲染之前初始化它，并且您的目标元素在滚动之前已经可见，则需要在页面渲染后重新检查滚动位置。

// after DOM has rendered
countUp.handleScroll();

使用插件进行替代动画

目前只有一个插件，即 Odometer 插件。

要使用插件，您首先需要安装插件包。然后您可以包含它并使用插件选项。有关更详细的信息，请参阅每个插件的文档。

const countUp = new CountUp('targetId', 5234, {
  plugin: new Odometer({ duration: 2.3, lastDigitDelay: 0 }),
  duration: 3.0
});

如果您想制作自己的插件，请参阅下面的 文档！

包含 CountUp

CountUp 以 ES6 模块的形式发布，因为它是浏览器中最标准化和兼容性最广泛的模块，尽管还包含了一个 UMD 模块（见下文链接），以及一个独立的 requestAnimationFrame 补充包（见下文）。

对于下面的示例，首先安装 CountUp。这将为您带来最新的版本。

npm i countup.js

使用 vanilla js 的示例

这是我在演示中使用的内容。查看 index.html 和 demo.js。

main.js

import { CountUp } from './js/countUp.min.js';

window.onload = function() {
  var countUp = new CountUp('target', 2000);
  countUp.start();
}

在您的 html 中包含它。注意 type 属性。

<script src="./main.js" type="module"></script>

为了支持 IE 和旧版浏览器，使用 nomodule 脚本来包含不使用模块语法的独立脚本。

<script nomodule src="js/countUp.umd.js"></script>
<script nomodule src="js/main-for-legacy.js"></script>

要在本地运行启用模块的脚本，您需要一个简单的本地服务器设置，例如 这个（通过运行 npm run serve 在本地测试演示），否则当浏览器尝试将脚本作为模块加载时，您可能会看到 CORS 错误。

对于 Webpack 和其他构建系统

从包中导入，而不是文件位置。

import { CountUp } from 'countup.js';

UMD 模块

CountUp 还在 ./dist/countUp.umd.js 中作为 UMD 模块封装，并在全局 window 范围内公开 CountUp。要使用它，请将 countUp.umd.js 包含在脚本标签中，并按如下方式调用：

var numAnim = new countUp.CountUp('myTarget', 2000);
numAnim.start()

requestAnimationFrame 补充包

如果您想支持 IE9 及更早版本和 Opera mini，可以包含 dist/requestAnimationFrame.polyfill.js。

贡献

在提交拉取请求之前，请务必遵循以下说明

1. 在 src/countUp.ts 上进行工作。
2. 代码检查：npm run lint
3. 运行测试：npm t
4. 通过运行 npm start 构建并运行演示，然后检查演示以确保它能够计数。

创建动画插件

从 v2.6.0 版本开始，CountUp 支持插件。插件实现它们自己的渲染方法来显示每帧的格式化值。可以将类实例或对象传递给 CountUpOptions 的 plugin 属性，然后调用插件的渲染方法而不是 CountUp 的。

export declare interface CountUpPlugin {
  render(elem: HTMLElement, formatted: string): void;
}

插件的一个示例

export class SomePlugin implements CountUpPlugin {
  // ...some properties here

  constructor(options: SomePluginOptions) {
    // ...setup code here if you need it
  }

  render(elem: HTMLElement, formatted: string): void {
    // render DOM here
  }
}

如果您创建了一个插件，请确保创建一个 PR 来将其添加到本 README！