tsParticles Particles Bundle 实战指南用tsparticles/particles快速构建轻量级粒子背景【免费下载链接】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/tsparticlestsparticles/particles是 tsParticles 项目中的一个聚焦型 bundle专为创建简单粒子效果而设计提供了以particles函数为核心的极简 API是纯粒子背景场景如网站登录页、落地页的动态背景的最轻量选择之一。读完本文你将掌握该 bundle 的安装方式、particles()/particles.create()/particles.init()三种调用形态、全部高层选项及其默认值、返回实例的控制方法并通过源码理解高层选项到引擎配置的映射原理与实例缓存机制。什么是 Particles BundletsParticles 的particlesbundle 定位是以聚焦 API 创建简单粒子效果。与 confetti、fireworks 等特效型 bundle 不同它不包含彩带、烟花等额外功能只覆盖粒子背景最常用的能力粒子数量、颜色、形状、运动、连线links与碰撞collisions。从 package.json 的description可以看到它的官方定位Minimal tsParticles particles bundle — lightweight particle engine without confetti or fireworks extras. Perfect for pure particle backgrounds最小化的 tsParticles 粒子 bundle——没有 confetti 或 fireworks 附加功能非常适合纯粒子背景。当前仓库中该包版本为4.3.3。包含的依赖包bundle 通过组合以下包实现开箱即用依赖关系见 package.json包名仓库位置作用tsparticles/basic及全部依赖bundles/basic提供基础加载器loadBasic注册圆形 shape、移动插件、透明度/尺寸/出界更新器等tsparticles/engineengine核心引擎负责容器、粒子、画布渲染与生命周期tsparticles/plugin-interactivityplugins/interactivity交互性插件鼠标事件相关tsparticles/interaction-particles-collisionsinteractions/particles/collisions粒子与粒子之间的碰撞交互tsparticles/interaction-particles-linksinteractions/particles/links粒子之间的连线交互其中tsparticles/basic本身又聚合了一组插件blend、hex/hsl/rgb 颜色插件、move 插件、circle 形状、paint/opacity/outModes/size 更新器具体见 bundles/basic/src/index.ts 的loadBasic实现。也就是说particlesbundle 在初始化时会通过 particles.ts 的doInitPlugins一次性注册上述全部插件。暴露的 API以particles为核心bundle 的公开 API 全部围绕particles展开。根据 particles.ts 的函数签名particles同时支持三种调用方式import { particles } from tsparticles/particles; // 主 API const instance await particles(); // 使用默认 id particles 与默认选项 const byId await particles(canvas-id, options); // 指定容器 id 与选项 const byOptions await particles(options); // 仅传选项使用默认 id particles // 额外辅助 await particles.init(); // 仅初始化插件不创建动画 const custom await particles.create(canvas, options); // 绑定到指定 canvas 元素 console.log(particles.version); // 当前 bundle 版本号几个值得注意的细节主入口不暴露tsParticles。README 明确说明tsparticles/particles的主入口不会导出tsParticles需要直接使用引擎 API 时应从tsparticles/engine导入。这一点在源码中得到印证主入口 index.ts 只导出了ParticlesOptions类型与particles函数。参数识别逻辑当第一个参数是字符串时被当作id第二个参数作为选项否则第一个参数整体作为选项对象id 固定为particles。对应实现见 particles.ts。全局挂载无论哪个入口模块加载后都会执行globalThis.particles particles见 particles.ts因此在浏览器中可以直接调用全局particles函数。入口形态与导出的差异仓库中提供了多个入口文件服务于不同的打包与使用场景index.ts标准 ES/CommonJS 主入口export * from ./particles.js。particles.lazy.ts懒加载实现通过import(tsparticles/basic/lazy)等动态导入按需加载各插件包减少首屏加载体积。index.lazy.ts懒加载入口的类型出口对应包导出的./lazy子路径见 package.json。browser.ts浏览器全局版本额外挂载__tsParticlesInternals内部对象。bundle.ts完整 bundle 版本除particles外还会把tsParticles挂到全局。安装使用 pnpm 安装仓库本身采用 pnpm workspace 管理见根目录 pnpm-workspace.yamlpnpm add tsparticles/particles如果你希望依赖在运行时按需加载可以使用懒加载入口import { particles } from tsparticles/particles/lazy;两种入口的 API 完全一致区别仅在于依赖的加载时机懒加载版本会在首次调用时动态import各个插件包见 particles.lazy.ts适合对首屏体积敏感的场景。基本使用创建粒子动画最简方式就是传入一个高层选项对象import { particles } from tsparticles/particles; const instance await particles({ count: 120, color: #00f, links: true, linksColor: #0ff, linksLength: 140, radius: 4, shape: [circle, square], }); instance?.pause(); instance?.play(); instance?.stop();这段示例展示了核心链路particles(options)返回一个ParticlesInstance或undefined随后即可通过实例方法控制动画暂停、恢复与停止。由于particles是异步函数务必使用await等待实例就绪。自定义 canvasparticles.create如果不想使用全屏默认容器而是把粒子渲染到页面中已有的canvas元素上使用particles.createimport { particles } from tsparticles/particles; const canvas document.getElementById(my-canvas) as HTMLCanvasElement; await particles.create(canvas, { links: true });create的实现particles.ts会以canvas?.id ?? particles作为实例缓存 id并把 canvas 元素透传给引擎。在 utils.ts 的getDefaultOptions中可以看到只要传入 canvasfullScreen.enable就会被设为false粒子效果将限定在该 canvas 范围内渲染反之则默认启用全屏。选项详解IParticlesOptions接口定义了 bundle 全部高层选项见 IParticlesOptions.ts类型为RecursivePartial意味着所有字段均可选。下表汇总了 README 列出的选项并补充了源码 utils.ts 中的默认值选项类型默认值说明countNumber80粒子数量radiusNumber或RangeValue3粒子半径支持范围值linksBooleanfalse是否启用粒子间连线linksLengthNumber100连线最大距离像素linksColorString#fff连线颜色speedNumber或RangeValue3粒子移动速度支持范围值collisionsBooleanfalse是否启用粒子碰撞opacityNumber1粒子不透明度shapeString或ArrayStringcircle粒子形状类型可传数组随机选取colorString#fff粒子颜色其中RangeValue与SingleOrMultiple均来自tsparticles/engine见 IParticlesOptions.tsradius/speed支持传入如{ min: 1, max: 5 }的范围对象shape支持传入形状名称数组以随机混用多种形状。高层选项如何映射到引擎配置这是理解 bundle 内部机制的关键。getParticlesInstanceutils.ts会先调用getDefaultOptions把高层选项翻译成引擎的ISourceOptions再交给engine.load()fullScreen: { enable: !canvas }, particles: { number: { value: options.count ?? 80 }, color: { value: options.color ?? #fff }, links: { enable: options.links ?? false, color: options.linksColor ?? #fff, distance: options.linksLength ?? 100 }, collisions: { enable: options.collisions ?? false }, move: { enable: true, speed: options.speed ?? 3 }, opacity: { value: options.opacity ?? 1 }, shape: { type: options.shape ?? circle }, size: { value: options.radius ?? 3 }, }映射关系一目了然count → particles.number.value、radius → particles.size.value、linksLength → particles.links.distance、shape → particles.shape.type。同时可以看到move.enable恒为true即粒子始终处于运动状态这是粒子背景的默认行为。返回实例的方法particles()与particles.create()均返回ParticlesInstance。该类是对引擎Container的轻量封装见 ParticlesInstance.ts对外暴露方法说明pause()暂停粒子动画内部调用container.pause()play()恢复播放内部调用container.play()stop()停止动画内部调用container.stop()destroy()销毁容器并从内部缓存中移除该实例此外还提供只读属性destroyed用于判断底层容器是否已被销毁。需要说明的是README 只列了前三个方法destroy()与destroyed可从源码 ParticlesInstance.ts 确认存在同样可用于实例生命周期管理。实例缓存机制bundle 在模块内部维护了一个Mapstring, ParticlesInstance | PromiseParticlesInstance | undefined见 utils.ts以 id 为键缓存实例。其行为并发去重若缓存中已存在进行中的 Promiseexisting instanceof Promise直接返回该 Promise避免同一 id 重复创建utils.ts。存活复用若缓存实例未被销毁直接返回既有实例utils.ts。销毁清理实例已销毁则从缓存删除并重建destroy()也会通过deleteParticlesInstance清理缓存条目ParticlesInstance.ts。这正是 README常见陷阱中提醒不要无意中复用同一个 id的原因由于缓存以 id 为键重复传入相同 id 会拿到同一个已存在实例而非新建动画。常见陷阱README 明确列出了三个高频踩坑点结合源码进一步说明在 CDN 脚本加载完成前调用particles。bundle 的初始化依赖动态import各插件包脚本未就绪时调用会失败。应确保引入脚本在调用前完成加载或在模块环境如 Vite、Webpack中通过import使用。误以为tsparticles/particles主入口会导出tsParticles。主入口只导出particles与ParticlesOptions类型见 index.ts需要引擎 API 时请直接import { tsParticles } from tsparticles/engine。无意中复用同一个 id。实例按 id 缓存默认 id 为particles重复调用相同 id 不会创建新实例。多个独立粒子场景请使用不同 id或用particles.create绑定不同 canvas。何时选择 Particles Bundle选择tsparticles/particles的典型场景是只需要纯粒子背景粒子数量、颜色、移动、连线、碰撞这几个维度即可覆盖大部分背景需求。它的优势在于 API 极简——无需直接接触引擎的深层配置结构一个扁平选项对象即可启动。而如果还需要 confetti 彩带、fireworks 烟花或其他特效能力仓库中提供了对应的 bundle如 bundles/confetti、bundles/fireworks、bundles/all可按需选择。相关的中文配置参考也可以查看 markdown/Options.md 与 markdown/Options 目录下的文档。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考