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 srcparticles.min.js/script改为script srctsparticles.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.jstsParticlesparticlesJS(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 更丰富字段类型作用elementHTMLElement \| OffscreenCanvas直接指定渲染目标元素而不是仅靠 id 查找idstring容器 id不传时引擎会生成tsparticles 随机数indexnumber当options或url是数组时指定取数组中的哪一项optionsISourceOptions \| ISourceOptions[]内联配置对象可传数组urlstring \| 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.loadJSON 文件加载与particlesJS.setOnClickHandler也都做了兼容实现。也就是说兼容层不只是能跑而是做了非常细致的配置字段级翻译让旧配置即使不改名也能得到正确的视觉结果。不过官方依然推荐兼容层只用于过渡长期维护应迁移到新的tsParticlesAPI。3) 更新配置选项从snake_case到camelCase3.1 必须更新的核心字段许多旧选项在新引擎中仍然可用但推荐尽快更新旧写法particles.js新写法tsParticlesline_linkedlinksretina_detectdetectRetina其他snake_case字段对应camelCase字段更完整的映射示例可从兼容层源码 particles.ts 反推旧写法新写法说明number.density.value_areanumber.density.width密度检测区域由面积改为宽度/高度维度shape.polygon.nb_sidesshape.options.polygon.sides多边形边数interactivity.modes.push.particles_nbinteractivity.modes.push.quantity点击 push 新增粒子数interactivity.modes.remove.particles_nbinteractivity.modes.remove.quantity点击 remove 减少粒子数opacity.anim.opacity_minopacity.animation.minimumValue或value为区间透明度动画最小值size.anim.size_minsize.animation.minimumValue或value为区间尺寸动画最小值move.attract.rotateX / rotateYmove.attract.rotate.x / rotate.y吸引旋转分量另外注意几个行为差异detectRetina默认值在新引擎中为true旧库默认false迁移后高 DPI 屏幕上的粒子会明显更清晰但也会带来少量性能开销粒子移动速度存在一个换算系数兼容层中speed: fixedOptions.particles.move.speed / speedFactorspeedFactor 3见 particles.ts。也就是说同样的数值在 tsParticles 下需要除以 3 才与原视觉速度一致——如果你直接照搬旧配置觉得太快这是原因所在。3.2 利用控制台警告定位未迁移字段如果看到控制台出现警告信息请把它当作配置升级的向导逐条对照更新你的配置文件即可。这也意味着你完全不需要一次性重写——先跑起来再按警告逐个字段清理。4) 常见迁移陷阱只改了脚本名忘了改模板中的 DOM id / classparticlesJS(particles-js, ...)对应的容器 id 仍是particles-js但迁移后若使用tsParticles.load({ id: tsparticles })HTML 中必须有div idtsparticles/div否则引擎会自动在body尾部创建同名 canvas见 engine/src/Core/Engine.ts 的getDomContainer逻辑布局上容易凭空多出一个元素。API 迁移了但选项键仍是snake_case虽然兼容层能兜底但直接使用新 API 时建议同步改掉旧键名避免与类型定义、文档示例产生歧义。把回调参数传给loadJSONloadJSON没有第三个参数回调式写法会静默失效务必改成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 倍率【免费下载链接】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），仅供参考