tsParticles Confetti Bundle 实战指南：用 @tsparticles/confetti 一行代码打造五彩纸屑特效

tsParticles Confetti Bundle 实战指南：用 @tsparticles/confetti 一行代码打造五彩纸屑特效

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles

导读

@tsparticles/confetti是 tsParticles 官方提供的彩带（confetti）专用聚合包，它将粒子引擎、发射器插件、运动插件以及卡片、爱心、星形等形状和旋转、摆动、翻滚等更新器封装成一个开箱即用的confettiAPI。本文以 bundles/confetti/README.md 为核心骨架，结合该包源码（bundles/confetti/src）深入讲解其安装方式、两种调用范式、完整配置参数、CDN 用法与常见坑位，读完即可在任意前端项目或纯 HTML 页面中落地页面庆祝、按钮反馈、抽奖动画等纸屑特效。

包内组成：一个 API，聚合整条粒子技术栈

@tsparticles/confetti不只是一个函数，它通过依赖聚合把渲染彩带效果所需的全部能力打包在一起。按 bundles/confetti/package.json 的dependencies声明，其包含以下包：

从 confetti.ts 的doInitPlugins可以看到，每次调用confetti()前会把这些 loader 一次性注册进引擎：loadBasic、loadEmittersPluginSimple、loadMotionPlugin、loadCardSuitsShape、loadHeartShape、loadImageShape、loadPolygonShape、loadSquareShape、loadStarShape、loadEmojiShape，以及loadRotateUpdater、loadLifeUpdater、loadRollUpdater、loadTiltUpdater、loadWobbleUpdater。正因为注册了这些形状与更新器，彩带才能在空中翻滚、摆动、倾斜地飘落。

其依赖关系可以直观地用 README 中的依赖图表示：

对外 API：围绕confetti的四个入口

该包的全部 API 都集中在confetti这一个函数对象上，源码中 confetti.ts 与 types.ts 定义了如下形态：

import { confetti } from "@tsparticles/confetti"; // 主 API：两种调用形式 await confetti(options); await confetti("canvas-id", options); // 附加辅助方法 await confetti.init(); // 仅初始化插件，不播放动画 const fireOnCanvas = await confetti.create(canvas, defaultOptions); // 绑定自定义 canvas await fireOnCanvas(options); // 通过返回的局部函数播放 console.log(confetti.version); // 打印包版本号

几个关键设计点，值得结合源码理解：

• 首参即分派：confetti的第一个参数ConfettiFirstParam是string | RecursivePartial<IConfettiOptions>联合类型。传入字符串时把它当作 canvas 的id，其余情况视为配置对象，并自动使用默认 id"confetti"。
• 返回 Container：每次调用返回Promise<Container | undefined>，便于进一步操作 tsParticles 容器实例。
• 主入口不导出引擎：@tsparticles/confetti的主入口（index.ts）刻意不暴露tsParticles。如果确实需要引擎底层 API，请直接从@tsparticles/engine导入。不过 browser.ts 这种用于 CDN 打包的入口会额外把tsParticles挂到globalThis上。
• confetti.create返回偏函数：它会基于传入的 canvas 生成一个"局部 confetti"，该函数后续调用时自动复用绑定好的 canvas 与默认配置，见 confetti.ts。
• confetti.version注入构建版本：版本号通过 rollup 构建时的__VERSION__宏注入，构建配置见 rollup.config.js。

安装与模块加载

通过包管理器安装（仓库使用 pnpm workspace 管理，命令如下）：

pnpm add @tsparticles/confetti

安装后，package.json 的exports字段提供了两条子路径：

• 主入口@tsparticles/confetti：默认 ESM，同时提供types、browser、import、require四种条件导出，覆盖 TypeScript、浏览器直引与 CommonJS 场景；
• 懒加载入口@tsparticles/confetti/lazy：所有依赖改为运行时动态import()（见 confetti.lazy.ts），适合对首屏体积敏感、希望按需拉取依赖的 ESM 项目。

快速上手：三种典型用法

1. ESM / TypeScript：全局全屏彩带

不指定 canvas 时，特效会以全屏浮层的方式播放（对应fullScreen.enable: true），适合页面级庆祝：

import { confetti } from "@tsparticles/confetti"; await confetti({ count: 80, spread: 60, position: { x: 50, y: 50 }, colors: ["#ffffff", "#ff0000"], });

2. 指定已有 canvas id

传入 id 时，特效会渲染到页面中 id 匹配的 canvas 元素上：

import { confetti } from "@tsparticles/confetti"; await confetti("tsparticles", { count: 50, angle: 90, spread: 45, });

3. 绑定自定义 canvas：confetti.create

适合把彩带约束在某个局部 DOM 区域（如按钮、卡片）内。它返回一个已经绑定好 canvas 的函数，后续每次调用只需传覆盖配置：

import { confetti } from "@tsparticles/confetti"; const canvas = document.getElementById("my-canvas") as HTMLCanvasElement; const localConfetti = await confetti.create(canvas, { count: 30 }); await localConfetti({ spread: 70 });

从源码看，confetti.create会先读取 canvas 的id属性（没有则用默认"confetti"）并回写该属性，随后创建容器；返回的闭包再次调用时复用同一个 canvas，实现"一次绑定、多次发射"。

CDN / Vanilla JS / jQuery 用法

CDN 场景提供两个文件，均来自 rollup.config.js 的打包产物：

• Bundle 文件：所有依赖内联进一个脚本，加载后confetti直接挂在globalThis（即浏览器中的window.confetti），开箱即用；
• 非 Bundle 文件：只包含confettiAPI 本身，页面必须按Included Packages一节列出的依赖顺序手动逐个加载脚本，配置成本更高。

Bundle 加载后的典型用法：

<script src="https://cdn.example.com/@tsparticles/confetti/bundle.min.js"></script> <script> // 方式一：直接触发 confetti({ count: 60 }); // 方式二：异步等待播放完成 (async () => { await confetti({ count: 60, spread: 55 }); })(); // 方式三：指定目标 canvas confetti("tsparticles", { count: 50, position: { x: 50, y: 50, }, }); </script>

注意：非 Bundle 方案中globalThis.confetti的挂载逻辑见 browser.ts（只挂confetti），而完整 Bundle 的入口 browser.ts 还会额外暴露tsParticles。

完整参数表与默认值

confettiAPI 接受两种签名：confetti(options)与confetti(id, options)。所有配置都实现于 ConfettiOptions.ts 的构造器默认值，汇总如下：

默认色板为 7 色糖果色：

["#26ccff", "#a25afd", "#ff5e7e", "#88ff5a", "#fcff42", "#ffa62d", "#ff36ff"]

兼容的废弃别名（仍被接受，但建议迁移）：

• particleCount→ 用count；
• origin→ 用position（origin按 0~1 归一化值换算，见 ConfettiOptions.ts 的 getter/setter）。

参数背后的引擎映射：源码级原理

confetti之所以"轻"，是因为它在内部把一套精简的配置翻译成完整的 tsParticles 源配置（utils.ts 的convertOptions），几个值得注意的换算：

• 物理量换算：gravity * 9.81作为重力加速度，startVelocity * 3作为初速度，1 - decay作为速度衰减率，spread映射为移动角度、angle取负作为移动方向；
• 发射模型：粒子数不直接写在particles.number，而是通过 emitters 插件在life: { duration: 0.1, count: 1 }的瞬间一次性喷出（startCount），并配合透明度从max衰减到min的动画营造"消散"感；
• ticks换算透明度速度：opacitySpeed = 120 * 100 / (60 * ticks)，即动画帧率按 120 FPS、基准 60 FPS 折算，确保纸屑在指定帧数内完成淡出；
• reduced-motion 降级：disableForReducedMotion直接映射到motion.disable，由 motion 插件检测prefers-reduced-motion后跳过动画；
• 复用优化：setConfetti内部维护了一个ids -> Container的 Map（utils.ts）。若同一 id 的容器仍存活，后续调用走addEmitter快速路径，直接在原容器上再喷一轮，避免重复建容器；并发调用期间则用 Promise 加锁等待初始化完成。

常见坑位与规避

README 明确列出了三个最常见的坑：

1. CDN 场景过早调用：脚本尚未加载完成就调用confetti，会得到 undefined 或直接报错。应等待 DOM/脚本就绪，或使用(async () => { await confetti(...) })()形式，把调用放进异步上下文。
2. 误以为主入口导出tsParticles：@tsparticles/confetti主入口只导出confetti，需要引擎 API 时请从@tsparticles/engine单独导入。
3. TypeScript 下不传首参：confetti的第一个参数是必填的，要么传配置对象（confetti(options)），要么传 id + 配置（confetti(id, options)），不能无参调用。

延伸：配套的 confetti 预设与示例

除直接使用该 bundle 外，仓库内还提供了基于它的高阶预设与模板，可直接参考：

• 预设：@tsparticles/preset-confetti、@tsparticles/preset-confettiCannon、@tsparticles/preset-confettiExplosions、@tsparticles/preset-confettiFalling、@tsparticles/preset-confettiParade，分别对应礼炮、爆炸、飘落、游行的成品动画；
• 演示模板：templates/confetti 与 demo 目录下提供多框架可运行示例；
• 完整配置参考：markdown/Options.md 与 markdown/Options 目录覆盖引擎级全部选项说明。

小结

@tsparticles/confetti以"单个confetti函数"作为统一入口，背后聚合了引擎、发射器、运动插件与十余个形状/更新器模块，是 tsParticles 生态中把"彩带特效"这件事做到极简的官方方案。无论是全屏庆祝、局部 canvas 绑定，还是 CDN 快速接入，本文给出的 API 形态、参数表与源码换算逻辑都足以支撑你在生产项目中直接落地，并能在需要时无缝下沉到引擎层做深度定制。

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles