浏览器中的高性能五彩纸屑动画.docx - Word

GitHub - catdad/canvas-confetti:🎉浏览器中的高性能五彩纸屑动画 --- GitHub - catdad/canvas-confetti: 🎉 performant confetti animation in the browser

演示

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>

注意:您应该在包含项目时使用最新版本。您可以在 releases 页面上查看所有版本。

减少运动

感谢您和我一起讨论关于您网站上运动的非常重要的信息。你看,不是每个人都喜欢它,有些人实际上更喜欢不动。他们有办法告诉我们,我们应该倾听。虽然我不想告诉你现在不要在你的页面上有五彩纸屑,但我确实想让你很容易尊重你的用户想要的东西。您可以使用一个 disableForReducedMotion 选项,这样对混乱动画有问题的用户就不需要在您的网站上苦苦挣扎。默认情况下,这是禁用的,但我正在考虑在未来的主要版本中更改它。如果您对此有强烈的感受,请告诉我。现在,请负责任地使用五彩纸屑。

应用程序接口

从 npm 安装时,此库可能需要作为项目构建中的客户端组件。使用 CDN 版本时,它会在 window 上显示为五彩纸屑函数。

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

confetti 接受一个可选对象。当窗口。Promise 可用,它将返回一个 Promise 以通知您何时完成。当 promise 不可用时(就像在 IE 中一样),它将返回 null。你可以使用任何流行的 polyfill 对 promise 进行 polyfill。您还可以通过以下方式为 confetti 提供 promise 实现:

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

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

选项

confetti 参数是一个可选的 options 对象,它具有以下属性:

  • particleCountInteger (默认值:50):要启动的五彩纸屑的数量。越多越有趣......但要酷一点,这涉及到很多数学。
  • angleNumber (default: 90):发射五彩纸屑的角度,以度为单位。90 是笔直向上的。
  • spreadNumber (default: 45):五彩纸屑可以偏离中心多远,以度为单位。45 表示五彩纸屑将以定义的角度正负 22.5 度发射。
  • startVelocityNumber (default: 45):五彩纸屑开始移动的速度,以像素为单位。
  • decayNumber (default: 0.9):五彩纸屑失去速度的速度。将此数字保持在 0 到 1 之间,否则五彩纸屑会加速。更好的是,永远不要改变它。
  • 重力数 (默认值:1):粒子被拉低的速度。1 是全重力,0.5 是半重力,依此类推,但没有限制。如果您愿意,您甚至可以使粒子上升。
  • driftNumber (default: 0)(漂移数字 (默认:0)):五彩纸屑将漂移到一侧的程度。默认值为 0,这意味着它们将直接下降。对 left 使用负数,对 right 使用正数。
  • 平面布尔值 (default: false):(可选)关闭三维五彩纸屑在现实世界中可能具有的倾斜和摆动。是的,他们看起来有点难过,但你们都要求他们,所以不要怪我。
  • ticksNumber (default: 200):五彩纸屑移动的次数。这是抽象的......但是,如果五彩纸屑对您来说消失得太快,请玩弄它。
  • originObject:从何处开始发射五彩纸屑。如果您愿意,请随时在屏幕外启动。
    • origin.xNumber (default: 0.5):页面上的 x 位置,其中 0 是左边缘,1 是右边缘。
    • origin.yNumber (default: 0.5):页面上的 y 位置,其中 0 是上边缘,1 是下边缘。
  • colors数组<String>:十六进制格式的颜色字符串数组...你知道的,就像 #bada55 一样。
  • shapes数组<String|Shape>:五彩纸屑的形状数组。有 3 个内置值 square、circle 和 star。默认设置是在均匀混合中同时使用正方形和圆形。要使用单个形状,您可以在数组中只提供一个形状,例如 ['star']。您还可以通过提供一个值来更改组合,例如 ['circle', 'circle', 'square'] 使用两个第三个圆和一个第三个正方形。您还可以使用 confetti.shapeFromPath 或 confetti.shapeFromText 帮助程序方法创建自己的形状。
  • 标量数 (默认值:1): 每个五彩纸屑粒子的比例因子。使用小数点使五彩纸屑更小。继续,试试微小的五彩纸屑,它们很可爱!
  • zIndexInteger (默认值:100): 毕竟,五彩纸屑应该在上面。但是如果你有一个疯狂的高页,你可以把它设置得更高。
  • disableForReducedMotion 布尔值 (default: false): 为喜欢减少运动的用户完全禁用五彩纸屑。在这种情况下, confetti() promise 将立即解决。

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

此帮助程序方法允许您使用 SVG 路径字符串创建自定义五彩纸屑形状。任何有效的路径都应该有效,但有一些注意事项:

  • 将对所有路径进行归档。如果您希望有一个描边路径,则不会实现。
  • 路径仅限于单一颜色,因此请记住这一点。
  • 所有路径都需要一个有效的转换矩阵。您可以传入一个矩阵,也可以省略它,并使用此帮助程序为您计算矩阵。 请注意,计算矩阵有点昂贵,因此最好为开发中的每个路径计算一次并缓存该值,以便生产五彩纸屑保持快速。矩阵是确定性的,并且在给定相同的 path 值的情况下将始终相同。
  • 为了获得最佳的向前兼容性,如果更新 canvas-confetti 库,最好重新生成并重新缓存矩阵。
  • 对基于路径的五彩纸屑的支持仅限于支持 Path2D 的浏览器,目前它应该是所有主要的浏览器。

这个方法将返回一个 Shape —— 它实际上只是一个具有一些属性的普通对象,但是 shhh...我们将假装它是一个形状。将此 Shape 对象直接传递到 shapes 数组中。

例如,以下是制作三角形五彩纸屑的方法:

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

confetti({
  shapes: [triangle]
});

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

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

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

  • 对于挥舞的五彩纸屑,大部分是方形的东西效果最好。也就是说,单个字符,尤其是表情符号。
  • 此帮助程序不是在每次绘制五彩纸屑时都呈现文本,而是实际上栅格化文本。因此,它在创建后不能很好地扩展。如果您打算使用标量值来缩放五彩纸屑,请在创建形状时在此处使用相同的标量值。这将确保五彩纸屑不会模糊。

此方法的选项包括:

  • 对象选项 :
    • textString:要渲染为五彩纸屑的文本。如果你拿不定主意,我建议你用 “🐈”。
    • scalarNumber, optional, default: 1: 相对于默认大小的缩放值。它与五彩纸屑选项中的标量值匹配。
    • color String, optional, default: #000000 :用于呈现文本的颜色。
    • fontFamily String, optional, default: native emoji :渲染文本时使用的字体系列名称。默认遵循 rendring 设备的本机 OS 表情符号的最佳实践 ,回退到 sans-serif。如果使用 Web 字体,请确保在渲染五彩纸屑之前加载此字体 。
var scalar = 2;
var pineapple = confetti.shapeFromText({ text: '🍍', scalar });

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

confetti.create(canvas, [globalOptions])function

此方法创建使用自定义画布的 confetti 函数的实例。如果要限制页面上出现五彩纸屑的区域,这将非常有用。默认情况下,此方法不会以任何方式修改画布(除了绘制到画布)。

不过,Canvas 可能会被误解一些,所以让我解释一下为什么你可能想让模块稍微修改一下 canvas。默认情况下, 画布是一个相对较小的图像 -- 大约 300x150,具体取决于浏览器。当您使用 CSS 调整其大小时,这将设置画布的显示大小,但不设置该画布上表示的图像。可以将其视为在 img 标签中加载 300x150 jpeg 图像,然后将该标签的 CSS 设置为 1500x600 -- 您的图像最终会变得拉伸和模糊。对于画布,您还需要设置画布图像本身的宽度和高度。如果您不想这样做,您可以允许 Confetti 为您设置它。

另请注意,您应该保留自定义实例,并避免多次初始化具有相同 canvas 元素的五彩纸屑实例。

以下全局选项可用:

  • resizeBoolean (default: false): 是否允许设置画布图像大小,以及在窗口大小发生变化时保持其大小正确(例如,调整窗口大小、旋转移动设备等)。默认情况下,不会修改画布大小。
  • useWorkerBoolean (default: false): 是否尽可能使用异步 Web Worker 来渲染五彩纸屑动画。默认情况下,此选项处于关闭状态,这意味着动画将始终在主线程上执行。 如果打开并且浏览器支持它,动画将在主线程之外执行,这样它就不会阻止您的页面需要执行的任何其他工作。使用此选项也会修改画布,但更多内容会直接在下面 - 请阅读它。 如果浏览器不支持,则将忽略此值。
  • disableForReducedMotion 布尔值 (default: false): 为喜欢减少运动的用户完全禁用五彩纸屑。当设置为 true 时,使用此五彩纸屑实例将始终尊重用户对减少运动的请求,并为他们禁用五彩纸屑。

重要提示:如果您使用 useWorker: true,则我现在拥有您的 Canvas。它现在是我的了,我可以用它做任何我想做的事情(别担心......我保证,我只会在里面放五彩纸屑)。您不得尝试以任何方式使用画布(除了我猜将其从 DOM 中删除),因为它会引发错误。 当使用 worker 进行渲染时,画布的控制权必须转移给 Web worker,以防止在主线程上使用该画布。如果必须以任何方式作画布,请不要使用此选项。

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

var myConfetti = confetti.create(myCanvas, {
  resize: true,
  useWorker: true
});
myConfetti({
  particleCount: 100,
  spread: 160
  // any other options from the global
  // confetti function
});

confetti.reset()

停止动画并清除所有五彩纸屑,并立即解决任何未完成的承诺。如果使用 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({
  particleCount: 150
});

发射一些非常宽的五彩纸屑:

confetti({
  spread: 180
});

发挥创意。从页面的随机部分发射一小堆五彩纸屑:

confetti({
  particleCount: 100,
  startVelocity: 30,
  spread: 360,
  origin: {
    x: Math.random(),
    // since they fall down, start a bit higher than random
    y: Math.random() - 0.2
  }
});

我说的是创意......我们可以做得更好。由于我们叫五彩纸屑多少次并不重要(只是空气中五彩纸屑的总数),我们可以做一些有趣的事情,比如在 30 秒内从多个方向连续发射越来越多的五彩纸屑:

// do this for 30 seconds
var duration = 30 * 1000;
var end = Date.now() + duration;

(function frame() {
  // launch a few confetti from the left edge
  confetti({
    particleCount: 7,
    angle: 60,
    spread: 55,
    origin: { x: 0 }
  });
  // and launch a few from the right edge
  confetti({
    particleCount: 7,
    angle: 120,
    spread: 55,
    origin: { x: 1 }
  });

  // keep going until we are out of time
  if (Date.now() < end) {
    requestAnimationFrame(frame);
  }
}());
第1页,共1页
本文共0个字符
中文(中国)
辅助功能
文档日期2025-03-25 9:19:47