canvas-confetti

演示

catdad.github.io/canvas-confetti

安装

你可以通过NPM安装这个模块作为组件：

npm install --save canvas-confetti

然后你可以在项目构建中使用require('canvas-confetti');来引入它。注意：这是一个客户端组件，不能在Node中运行。你需要使用类似webpack的工具来构建你的项目以便使用它。

你也可以直接从CDN在HTML页面中引入这个库：

<script src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js"></script>

注意：你应该使用在引入项目时的最新版本。你可以在发布页面查看所有版本。

减少动画

感谢你加入我这个关于网站动画的重要讨论。你看，并非所有人都喜欢动画，有些人甚至更喜欢没有动画。他们有方式告诉我们这一点，我们应该倾听。虽然我还不想让你完全放弃在页面上使用五彩纸屑，但我确实想让你更容易尊重用户的意愿。这里有一个disableForReducedMotion选项，你可以使用它来避免那些对混乱动画感到困扰的用户在你的网站上遇到麻烦。这个选项默认是禁用的，但我正在考虑在未来的主要版本中改变这一点。如果你对此有强烈的看法，请告诉我。现在，请负责任地使用五彩纸屑。

API

当从npm安装时，这个库可以作为客户端组件在你的项目构建中引入。当使用CDN版本时，它会作为window上的confetti函数暴露出来。

`confetti([options {Object}])` → `Promise|null`

confetti接受一个可选的对象参数。当window.Promise可用时，它会返回一个Promise来让你知道什么时候完成。当Promise不可用时（比如在IE中），它会返回null。你可以使用任何流行的polyfill来添加Promise支持。你也可以通过以下方式为confetti提供Promise实现：

const MyPromise = require('some-promise-lib');
const confetti = require('canvas-confetti');
confetti.Promise = MyPromise;

如果你在完成之前多次调用confetti，它每次都会返回相同的Promise。在内部，会重复使用相同的canvas元素，继续现有的动画并添加新的五彩纸屑。每次调用confetti返回的Promise会在所有动画完成后解决。

`options`

confetti参数是一个可选的options对象，它有以下属性：

particleCount 整数（默认：50）：要发射的五彩纸屑数量。越多越有趣...但要冷静，这涉及很多计算。
angle 数字（默认：90）：发射五彩纸屑的角度，以度为单位。90度是正上方。
spread 数字（默认：45）：五彩纸屑可以偏离中心多远，以度为单位。45意味着五彩纸屑将在定义的angle的基础上加减22.5度。
startVelocity 数字（默认：45）：五彩纸屑开始移动的速度，以像素为单位。
decay 数字（默认：0.9）：五彩纸屑失去速度的快慢。保持这个数字在0和1之间，否则五彩纸屑会加速。更好的是，永远不要改变它。
gravity 数字（默认：1）：粒子被向下拉的速度。1是完全重力，0.5是半重力，等等，但没有限制。如果你愿意，甚至可以让粒子向上飞。
drift 数字（默认：0）：五彩纸屑向侧面漂移的程度。默认是0，意味着它们会直接落下。使用负数向左漂移，正数向右漂移。
flat 布尔值（默认：false）：可选地关闭现实世界中三维五彩纸屑会有的倾斜和摆动。是的，它们看起来有点悲伤，但是你们要求的，所以别怪我。
ticks 数字（默认：200）：五彩纸屑移动的次数。这是抽象的...但如果五彩纸屑消失得太快，可以调整它。
origin 对象：从哪里开始发射五彩纸屑。如果你愿意，可以从屏幕外发射。
- origin.x 数字（默认：0.5）：页面上的x位置，0是左边缘，1是右边缘。
- origin.y 数字（默认：0.5）：页面上的y位置，0是顶部边缘，1是底部边缘。
colors 字符串数组：颜色字符串数组，使用HEX格式...你知道的，比如#bada55。
shapes 字符串|Shape数组：五彩纸屑的形状数组。有3个内置值：square、circle和star。默认是均匀混合使用正方形和圆形。要使用单一形状，你可以在数组中只提供一个形状，比如['star']。你也可以通过提供如['circle', 'circle', 'square']这样的值来改变混合比例，使用三分之二的圆形和三分之一的正方形。你还可以使用confetti.shapeFromPath或confetti.shapeFromText辅助方法创建自己的形状。
scalar 数字（默认：1）：每个五彩纸屑粒子的缩放因子。使用小数可以让五彩纸屑变小。来吧，试试超级小的五彩纸屑，它们很可爱！
zIndex 整数（默认：100）：五彩纸屑应该在最上面。但如果你的页面堆叠顺序很高，你可以设置得更高。
disableForReducedMotion 布尔值（默认：false）：对于偏好减少动画的用户完全禁用五彩纸屑。在这种情况下，confetti()Promise会立即解决。

`confetti.shapeFromPath({ path, matrix? })` → `Shape`

这个辅助方法让你可以使用SVG路径字符串创建自定义五彩纸屑形状。任何有效的路径都应该可以工作，不过有几点需要注意：

所有路径都会被填充。如果你希望有一个描边路径，这是没有实现的。
路径限制为单一颜色，请记住这一点。
所有路径都需要一个有效的变换矩阵。你可以传入一个，或者不传入并使用这个辅助方法为你计算矩阵。请注意，计算矩阵有点耗费资源，所以最好在开发时为每个路径计算一次矩阵并缓存该值，这样生产环境中的五彩纸屑就能保持快速。给定相同的路径值，矩阵是确定性的，总是相同的。
为了最好的向前兼容性，如果你更新了canvas-confetti库，最好重新生成并重新缓存矩阵。
基于路径的五彩纸屑支持仅限于支持Path2D的浏览器，这应该包括了所有主要的浏览器。

这个方法会返回一个Shape -- 它实际上只是一个带有一些属性的普通对象，但嘘...我们假装它是一个形状。直接将这个Shape对象传入shapes数组。

例如，这里展示了如何创建一个三角形五彩纸屑：

var triangle = confetti.shapeFromPath({ path: 'M0 10 L5 0 L10 10z' });

confetti({
  shapes: [triangle]
});

`confetti.shapeFromText({ text, scalar?, color?, fontFamily? })` → `Shape`

这是备受期待的渲染表情符号五彩纸屑的功能！使用任何标准的unicode表情符号。或者其他文本，但是...也许不要使用其他文本。

虽然任何文本都应该可以工作，但有一些注意事项：

对于飘动的五彩纸屑，大致呈正方形的东西效果最好。也就是说，一个单一字符，特别是表情符号。
这个辅助方法实际上是将文本栅格化，而不是每次绘制五彩纸屑时渲染文本。因此，创建后它不能很好地缩放。如果你计划使用scalar值来缩放你的五彩纸屑，在这里创建形状时使用相同的scalar值。这将确保五彩纸屑不会模糊。

这个方法的选项是：

options Object:
- text String: 要渲染为五彩纸屑的文本。如果你拿不定主意，我建议用"🐈"。
- scalar Number, 可选, 默认: 1: 相对于默认大小的缩放值。它与五彩纸屑选项中的scalar值匹配。
- color String, 可选, 默认: #000000: 用于渲染文本的颜色。
- fontFamily String, 可选, 默认: 原生表情符号: 渲染文本时使用的字体族名称。默认遵循渲染设备原生OS表情符号的最佳实践，回退到sans-serif。如果使用网络字体，请确保在渲染五彩纸屑之前加载此字体。

var scalar = 2;
var pineapple = confetti.shapeFromText({ text: '🍍', scalar });

confetti({
  shapes: [pineapple],
  scalar
});

`confetti.create(canvas, [globalOptions])` → `function`

这个方法创建一个使用自定义canvas的confetti函数实例。如果你想限制五彩纸屑出现在页面上的区域，这很有用。默认情况下，这个方法不会以任何方式修改canvas（除了在上面绘制）。 Canvas可能会被误解，所以让我解释一下为什么你可能想让模块稍微修改一下canvas。默认情况下，canvas是一个相对较小的图像——大约300x150，具体取决于浏览器。当你使用CSS调整其大小时，这只是设置了canvas的显示大小，而不是canvas上呈现的图像。可以将其想象为在img标签中加载一个300x150的jpeg图像，然后将该标签的CSS设置为1500x600——你的图像最终会被拉伸并变得模糊。对于canvas，你还需要设置canvas图像本身的宽度和高度。如果你不想这样做，可以让confetti为你设置。

还需注意，你应该保留自定义实例，并避免用同一个canvas元素多次初始化confetti实例。

以下全局选项可用：

resize 布尔值（默认：false）：是否允许设置canvas图像大小，以及在窗口大小改变时保持正确大小（例如调整窗口大小、旋转移动设备等）。默认情况下，canvas大小不会被修改。
useWorker 布尔值（默认：false）：是否在可能的情况下使用异步Web Worker来渲染confetti动画。默认关闭，意味着动画将始终在主线程上执行。如果开启并且浏览器支持，动画将在主线程之外执行，不会阻塞页面需要执行的任何其他工作。使用此选项也会修改canvas，但详情请直接看下面——请务必阅读。如果浏览器不支持，此值将被忽略。
disableForReducedMotion 布尔值（默认：false）：对于偏好减少动画的用户完全禁用confetti。设置为true时，此confetti实例的使用将始终尊重用户减少动画的请求，并为他们禁用confetti。

重要提示：如果你使用useWorker: true，我就拥有了你的canvas。它现在是我的了，我可以对它做任何事（别担心...我只会在里面放confetti，我保证）。你不能以任何方式使用canvas（除了从DOM中移除它），否则会抛出错误。使用Worker进行渲染时，必须将canvas的控制权转移给Web Worker，阻止主线程对该canvas的任何使用。如果你必须以任何方式操作canvas，请不要使用此选项。

var myCanvas = document.createElement('canvas'); document.body.appendChild(myCanvas);

var myConfetti = confetti.create(myCanvas, { resize: true, useWorker: true }); myConfetti({ particleCount: 100, spread: 160 // 可以使用全局confetti函数的任何其他选项 });

confetti.reset()

停止动画并清除所有confetti，同时立即解决任何未完成的promise。对于使用confetti.create创建的单独confetti实例，该实例将有自己的reset方法。

confetti();

setTimeout(() => { confetti.reset(); }, 100);

var myCanvas = document.createElement('canvas'); document.body.appendChild(myCanvas);

var myConfetti = confetti.create(myCanvas, { resize: true });

myConfetti();

setTimeout(() => { myConfetti.reset(); }, 100);

示例

以默认方式发射一些confetti：

confetti();

发射大量confetti：

confetti({ particleCount: 150 });

发射一些宽幅confetti：

confetti({ spread: 180 });

发挥创意。从页面的随机位置发射一小团confetti：

confetti({ particleCount: 100, startVelocity: 30, spread: 360, origin: { x: Math.random(), // 由于它们会向下落，所以起始位置比随机值稍高一些 y: Math.random() - 0.2 } });

我说要有创意...我们可以做得更好。由于调用confetti的次数并不重要（只关心空中confetti的总数），我们可以做一些有趣的事情，比如从多个方向连续发射越来越多的confetti，持续30秒：

// 持续30秒 var duration = 30 * 1000; var end = Date.now() + duration;

(function frame() { // 从左边缘发射一些confetti confetti({ particleCount: 7, angle: 60, spread: 55, origin: { x: 0 } }); // 从右边缘也发射一些 confetti({ particleCount: 7, angle: 120, spread: 55, origin: { x: 1 } });

// 继续执行，直到时间用完 if (Date.now() < end) { requestAnimationFrame(frame); } }());