tsParticles 迁移指南：从 particles.js 平滑升级完整实践-创锋一号

tsParticles 迁移指南：从 particles.js 平滑升级完整实践

【免费下载链接】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

导读：本指南以 markdown/pjsMigration.md 为骨架，系统讲解如何将基于 particles.js 的旧项目迁移到 tsParticles。内容覆盖脚本与 CSS 替换、JavaScript API 映射（particlesJS→tsParticles）、旧版snake_case选项的现代化改造，以及常见迁移陷阱。读完本文，你将掌握一套"换脚本 → 换选择器 → 换 API → 换选项"的四步增量迁移流程，并能借助 tsParticles 的兼容层、Promise 化接口与源码级参数映射把迁移风险降到最低。

tsParticles 是 particles.js 的官方后继项目，它不仅兼容 particles.js 的 API 与配置风格，还提供了更完整的 TypeScript 类型、更细粒度的模块化加载与可预期的异步生命周期。仓库中专门保留了bundles/pjs兼容包，其中 particles.ts 甚至内置了粒子数量密度（density）、碰撞（collisions）、吸引（attract）等配置的完整映射实现，保证旧配置能被逐字段翻译为新引擎可识别的选项。这使得"渐进式迁移"成为可能：不必一次性重写全部代码，而是分四步逐步切换。

1) 迁移脚本与 CSS 选择器

1.1 替换脚本文件

将页面中的 particles.js 脚本替换为 tsParticles 包：

<script src="particles.min.js"></script>

改为：

<script src="tsparticles.min.js"></script>

从源码结构看，engine/src/browser.ts 会直接把引擎单例挂载到全局对象上：globalObject.tsParticles = tsParticles，因此替换脚本后，window.tsParticles即可用。需要提醒的是：tsparticles.min.js是包含全部功能（形状、交互、插件）的全量包；如果你的页面只用到粒子背景 + 连线效果，可以改用更小的slim版本（对应bundles/slim），或者采用按需加载的方式，先加载引擎再通过loadFull(tsParticles)/loadSlim(tsParticles)注入所需能力。

1.2 更新 Canvas 的 CSS 类名

如果你为 canvas 写过自定义样式：

.particles-js-canvas-element { /* custom CSS */ }

应改为：

.tsparticles-canvas-element { /* custom CSS */ }

这是因为 tsParticles 的容器/画布元素统一使用tsparticles前缀的类名。若你希望完全保留旧样式，也可以把旧的.particles-js-canvas-element规则与新类名并存，在迁移过渡期同时生效。

2) 迁移 JavaScript API：从回调式到 Promise 式

2.1 快速映射表

particles.js	tsParticles
`particlesJS("id", options)`	`tsParticles.load({ id: "id", options })`
`particlesJS.load("id", "path", callback)`	`tsParticles.loadJSON("id", "path").then(...)`

2.2 旧代码（迁移前）

particlesJS.load("particles-js", "assets/particles.json", () => { console.log("callback - particles.js config loaded"); });

2.3 新代码（迁移后）

tsParticles.loadJSON("tsparticles", "assets/particles.json").then((container) => { console.log("callback - tsParticles config loaded", container); });

也可以直接传入内联配置对象：

tsParticles.load({ id: "tsparticles", options: { /* options */ }, });

注意：loadJSON不再接受第三个回调参数，请改用then(...)（或await）获取加载完成的Container实例。这是 API 从"回调式"转向"Promise 式"的最直观变化。

2.4 源码视角：`load`的加载链路

为什么load是 Promise 式的？看 engine/src/Core/Engine.ts 的load方法即可明白：它首先await this.init()完成插件初始化，随后解析id、url、index等ILoadParams参数（接口定义见 engine/src/Core/Interfaces/ILoadParams.ts），找到或创建 DOM 容器与 canvas，再await newItem.start()启动动画循环后才返回Container。因此调用方必须通过 Promise 才能拿到真正"已启动"的实例。

ILoadParams支持的可选字段比 particles.js 更丰富：

字段	类型	作用
`element`	`HTMLElement \\| OffscreenCanvas`	直接指定渲染目标元素，而不是仅靠 id 查找
`id`	`string`	容器 id；不传时引擎会生成`tsparticles + 随机数`
`index`	`number`	当`options`或`url`是数组时，指定取数组中的哪一项
`options`	`ISourceOptions \\| ISourceOptions[]`	内联配置对象（可传数组）
`url`	`string \\| string[]`	配置文件 URL（可传数组）；内部通过`fetch`获取后解析为配置

从源码看，load内部还会做一件旧库没有的事：如果发现同 id 的旧容器已存在，会先销毁旧实例再挂载新实例，避免重复叠加动画层。

2.5 兼容层：不换代码也能跑的`particlesJS`

如果你暂时不想改业务代码，tsParticles 的bundles/pjs包提供了完整的 particles.js 兼容层。查看 particles.ts 可以看到，particlesJS(tagId, options)内部会经过deepExtend合并默认配置，再把snake_case字段逐一翻译成新引擎配置（例如retina_detect→detectRetina、line_linked→links、particles_nb→quantity、value_area→width），最终调用engine.load(...)。甚至particlesJS.load（JSON 文件加载）与particlesJS.setOnClickHandler也都做了兼容实现。

也就是说，兼容层不只是"能跑"，而是做了非常细致的配置字段级翻译，让旧配置即使不改名也能得到正确的视觉结果。不过官方依然推荐：兼容层只用于过渡，长期维护应迁移到新的tsParticlesAPI。

3) 更新配置选项：从`snake_case`到`camelCase`

3.1 必须更新的核心字段

许多旧选项在新引擎中仍然可用，但推荐尽快更新：

旧写法（particles.js）	新写法（tsParticles）
`line_linked`	`links`
`retina_detect`	`detectRetina`
其他`snake_case`字段	对应`camelCase`字段

更完整的映射示例（可从兼容层源码 particles.ts 反推）：

旧写法	新写法	说明
`number.density.value_area`	`number.density.width`	密度检测区域由"面积"改为"宽度/高度"维度
`shape.polygon.nb_sides`	`shape.options.polygon.sides`	多边形边数
`interactivity.modes.push.particles_nb`	`interactivity.modes.push.quantity`	点击 push 新增粒子数
`interactivity.modes.remove.particles_nb`	`interactivity.modes.remove.quantity`	点击 remove 减少粒子数
`opacity.anim.opacity_min`	`opacity.animation.minimumValue`（或`value`为区间）	透明度动画最小值
`size.anim.size_min`	`size.animation.minimumValue`（或`value`为区间）	尺寸动画最小值
`move.attract.rotateX / rotateY`	`move.attract.rotate.x / rotate.y`	吸引旋转分量

另外注意几个行为差异：

detectRetina默认值在新引擎中为true（旧库默认false），迁移后高 DPI 屏幕上的粒子会明显更清晰，但也会带来少量性能开销；
粒子移动速度存在一个换算系数：兼容层中speed: fixedOptions.particles.move.speed / speedFactor（speedFactor = 3，见 particles.ts）。也就是说，同样的数值在 tsParticles 下需要除以 3 才与原视觉速度一致——如果你直接照搬旧配置觉得"太快"，这是原因所在。

3.2 利用控制台警告定位未迁移字段

如果看到控制台出现警告信息，请把它当作配置升级的向导，逐条对照更新你的配置文件即可。这也意味着你完全不需要"一次性重写"——先跑起来，再按警告逐个字段清理。

4) 常见迁移陷阱

只改了脚本名，忘了改模板中的 DOM id / class：particlesJS("particles-js", ...)对应的容器 id 仍是particles-js，但迁移后若使用tsParticles.load({ id: "tsparticles" })，HTML 中必须有<div id="tsparticles"></div>，否则引擎会自动在<body>尾部创建同名 canvas（见 engine/src/Core/Engine.ts 的getDomContainer逻辑），布局上容易"凭空多出一个元素"。
API 迁移了，但选项键仍是snake_case：虽然兼容层能兜底，但直接使用新 API 时建议同步改掉旧键名，避免与类型定义、文档示例产生歧义。
把回调参数传给loadJSON：loadJSON没有第三个参数，回调式写法会静默失效，务必改成then(...)。
一次改动过多、难以回滚：推荐按"脚本 → CSS → API → 选项"的顺序增量迁移，每步验证一次视觉效果，出现异常时能快速定位是哪个环节引入的。

5) 下一步

根选项与配置结构的完整说明：Options 总览；
各选项组的分项指南：Options 文档目录；
开箱即用的预制效果（presets）与可配置的 options 主题：可参考仓库中presets/、palettes/、utils/configs/下的真实配置示例，直接复制修改比从零手写更快；
若需要使用particlesJS兼容层，可查阅 bundles/pjs/README.md 了解其导出方式与initPjs用法。

附：迁移自检清单

完成迁移后，按以下清单核对，可显著降低遗留问题：

particles.min.js已替换为tsparticles.min.js（或按需加载的 slim/模块化方案）
模板中容器 id 与tsParticles.load({ id })/loadJSON("id")保持一致
自定义 canvas 样式的类名已从.particles-js-canvas-element更新
particlesJS(...)调用已替换为tsParticles.load({ id, options })
particlesJS.load(id, url, callback)已替换为tsParticles.loadJSON(id, url).then(...)
配置文件中line_linked、retina_detect等旧键已更新为links、detectRetina，其余键名已按camelCase处理
依据控制台警告逐条清理了剩余旧字段
视觉速度与原页面基本一致（注意 tsParticles 的speed数值约为 particles.js 的 1/3 倍率）

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析