tsParticles tsparticles/pjs 兼容层particles.js 旧 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在 tsParticles 仓库中tsparticles/pjs 是专为旧版 particles.js 项目准备的兼容compatibility包它把 VincentGarreau/particles.js 风格的particlesJS(...)函数 API以及 marcbruederlin/particles.js 风格的Particles.init(...)类 API映射到现代tsParticles引擎之上。需要注意的是该包被官方标记为 legacy 兼容胶水代码属于 obsolete 状态可能在 v5 中被移除新代码应直接使用tsParticlesAPI。读完本文你可以掌握initPjs(engine)的完整初始化流程与源码级实现细节、三类兼容全局对象particlesJS/pJSDom/Particles的语义与替代方案、旧版 options 到 tsParticles options 的字段转换规则以及从 particles.js 平滑迁移的推荐路径。包的定位与依赖结构tsparticles/pjs当前仓库内版本为4.3.3见 bundles/pjs/package.json其 npm 描述为 tsParticles particles.js compatibility layer — drop-in replacement for particles.js with full API compatibility and enhanced features。该包本身不含任何渲染逻辑它是一个聚合依赖的 bundle。READMEbundles/pjs/README.md列出的Included Packages为tsparticlesfull bundle及其全部依赖对应仓库目录 bundles/fulltsparticles/enginetsparticles/plugin-responsivepackage.json的dependencies字段与上述一致tsparticles、tsparticles/engine、tsparticles/plugin-responsive均为 workspace 依赖因此安装该包即自动获得完整引擎 响应式插件。从源码入口 bundles/pjs/src/index.ts 可以看到包对外只导出一个 APIimport { initPjs } from tsparticles/pjs;签名为initPjs(engine: Engine): Promisevoid关键点initPjs不返回兼容对象它的返回值类型是Promisevoid。它的职责是初始化兼容层并把兼容 API 挂到globalThis上。初始化流程initPjs(engine)在源码中做了什么bundles/pjs/src/index.ts 中initPjs的实现完整对应了 README 描述的三步流程const initPjs async (engine: Engine): Promisevoid { engine.checkVersion(__VERSION__); await engine.pluginManager.register(async e { await Promise.all([loadFull(e), loadResponsivePlugin(e)]); }); const { particlesJS, pJSDom } initParticlesJS(engine); globalThis.particlesJS particlesJS; globalThis.pJSDom pJSDom; globalThis.Particles MBParticles; };逐步拆解版本兼容检查engine.checkVersion(__VERSION__)校验运行时的 tsParticles 版本与兼容层版本是否匹配__VERSION__在构建时由打包器注入。注册插件通过engine.pluginManager.register注册一个异步加载函数loadFull来自tsparticlesfull bundle负责加载全部形状、交互、插件loadResponsivePlugin提供旧版responsive断点能力。注册是惰性的——真正的加载发生在引擎load容器时。创建并暴露三个 legacy 全局对象globalThis.particlesJSVincentGarreau 风格的加载函数含.load与.setOnClickHandler两个附加方法globalThis.pJSDom已加载容器Container[]数组globalThis.Particlesmarcbruederlin 风格的MBParticles静态类。这三个全局名在 bundles/pjs/src/index.ts 中通过declare global声明了 TypeScript 类型且全部标注deprecatedparticlesJS指向tsParticles.loadpJSDom指向tsParticles.domParticles指向直接tsParticles.load container 方法。此外仓库还提供lazy 入口bundles/pjs/src/index.lazy.ts其initPjs与标准入口逻辑相同但插件加载改为Promise.all([import(tsparticles), import(tsparticles/plugin-responsive)])动态import()用于支持按需加载code splitting场景进一步减小首屏 bundle 体积。安装模块方式使用README 推荐 pnpmpnpm add tsparticles/pjs tsparticles/engine安装后tsparticles/pjs的exports会按环境分发浏览器端走dist/browser/index.jsbrowser字段ES 走dist/esm/index.jsCJS 走dist/cjs/index.js类型来自dist/types/index.d.ts见 bundles/pjs/package.json 的exports/main/module/types字段。用法一ESM / TypeScript 中调用particlesJSimport { tsParticles } from tsparticles/engine; import { initPjs } from tsparticles/pjs; await initPjs(tsParticles); await globalThis.particlesJS(tsparticles, {/* particles.js-style options */});particlesJS(tagId, options)的完整签名定义在 bundles/pjs/src/VincentGarreau/IParticlesJS.ts(tagId: string, options: IParticlesJSOptions): PromiseContainer | undefined;它接收容器元素 id 与旧版 particles.js 选项对象返回 Promiseresolve 为 tsParticles 的Container实例加载失败时为undefined。旧版 options 如何被翻译成 tsParticles options这是兼容层最有价值的部分。bundles/pjs/src/VincentGarreau/particles.ts 中内置了一份完整的defaultPjsOptions与 particles.js 官网默认配置一致400 粒子、density.value_area: 800、line_linked.distance: 100、hover 为grab模式、click 为push模式等调用时先做deepExtend({}, defaultPjsOptions, options)深度合并再逐字段翻译成现代格式核心映射关系如下particles.js 旧字段tsParticles 新字段说明retina_detectdetectRetina视网膜屏检测interactivity.detect_oninteractivity.detectsOn交互检测区域interactivity.events.onhover/onclickinteractivity.events.onHover/onClick事件配置interactivity.modes.push.particles_nbinteractivity.modes.push.quantity点击生成的粒子数默认 4interactivity.modes.remove.particles_nbinteractivity.modes.remove.quantity点击移除的粒子数默认 2particles.line_linked.{enable,distance,color,opacity,width}particles.links.{enable,distance,color,opacity,width}连线配置particles.move.out_modeparticles.move.outModes边界行为particles.move.bounceparticles.collisions.enable碰撞反弹映射为碰撞开关particles.move.attract.{rotateX, rotateY}particles.attract.rotate.{x, y}吸引旋转参数particles.number.density.value_areaparticles.number.density.width密度基准面积particles.shape.stroke/shape.polygon.nb_sides/shape.imageparticles.stroke/particles.shape.options.polygon.sides/particles.shape.options.image形状配置particles.opacity.randomanimparticles.opacity.value { min, max }animation随机透明度变为 min/max 区间particles.size.randomanimparticles.size.value { min, max }animation随机尺寸变为 min/max 区间interactivity.events.resizeresize.enable窗口缩放监听源码中还有两个容易踩坑的细节速度换算move: { speed: fixedOptions.particles.move.speed / speedFactor }其中const speedFactor 3。即旧版speed: 2在新引擎中等效为speed: 2/3这是为了保持新旧版本粒子运动观感一致迁移时若直接照搬数值会发现粒子变快了。强制项翻译结果里固定写入fullScreen: { enable: false }和smooth: true即通过兼容层创建的容器默认不开全屏、始终平滑渲染。particlesJS上还有两个附加方法实现同在 particles.tsparticlesJS.load(tagId, pathConfigJson, callback)GET 请求加载 JSON 配置底层对应engine.load({ id, url })成功回调Container失败回调undefined。对应现代 API 为tsParticles.loadJSON(id, path).then(...)。particlesJS.setOnClickHandler(callback)为所有已加载容器附加点击回调底层转发到engine.pluginManager.setOnClickHandler对应现代 APItsParticles.setOnClickHandler。用法二Particles兼容类marcbruederlin 风格(async engine { await initPjs(engine); Particles.init({/* options */}); })(tsParticles);Particles指向 bundles/pjs/src/marcbruederlin/Particles.ts 中的MBParticles类提供静态init与实例方法pauseAnimation/resumeAnimation/destroy。Particles.init 选项仅适用于Particles.init选项类型默认值说明selectorstring-必填canvas 所在元素的 CSS 选择器maxParticlesinteger100粒子最大数量sizeVariationsinteger3尺寸变化幅度映射为 size 的 max 值min 固定为 1speedinteger0.5粒子运动速度colorstring 或 string[]#000000粒子颜色连线颜色固定为random随机色minDistanceinteger120连线距离pxconnectParticlesbooleanfalse是否绘制连线responsivearraynull断点数组每项含breakpoint与覆盖用options这些默认值与源码常量一一对应const linksMinDistance 120, moveMinSpeed 0.5, particlesMinCount 100, sizeMinValue 3Particles.ts 顶部。源码层面MBParticles.init的行为校验selector未提供或safeDocument().querySelector(selector)查不到元素时直接抛Error(No selector provided)/Error(No element found for selector)通过全局tsParticles实例异步engine.load(...)容器 id 取选择器去掉.和!后的文本断点转换responsive: [{ breakpoint, options }]映射为 tsParticles 的responsive: [{ maxWidth: breakpoint, options }]即视口宽度 ≤ breakpoint 时应用覆盖项返回一个持有#container私有引用的MBParticles实例后续方法均为容器操作的转发。方法方法说明底层转发pauseAnimation暂停粒子动画container.pause()resumeAnimation恢复粒子动画container.play()destroy销毁插件并清理资源container.destroy()用法三CDN / Vanilla JS / jQueryCDN 版本提供两种文件形态README 说明Bundle 版单文件包含全部依赖加载后直接调用initPjs(tsParticles)即可Not Bundle 版只含initPjs需要手动加载 Included Packages 一节列出的tsparticles、tsparticles/engine、tsparticles/plugin-responsive三个依赖。从入口源码看两者的差异这解释了为什么 Not Bundle 版依赖必须手动加载bundles/pjs/src/browser.ts仅把initPjs挂到globalThis.initPjs并初始化__tsParticlesInternals不导出tsParticlesbundles/pjs/src/bundle.ts除挂载initPjs外还globalThis.tsParticles tsParticles并export * from tsparticles/engine即 bundle 文件自带引擎实例页面中可直接initPjs(tsParticles)。加载 bundle 后的一次性初始化 双 API 用法// particles.jsVincentGarreau风格 (async engine { await initPjs(engine); particlesJS(tsparticles, {/* options */}); })(tsParticles);// marcbruederlin 风格 (async engine { await initPjs(engine); Particles.init({/* options */}); })(tsParticles);兼容全局对象速查表initPjs完成后可用的全局对象及现代等价 API全局对象说明现代等价particlesJSparticles.js 兼容加载函数另有.load与.setOnClickHandlertsParticles.load、tsParticles.loadJSON、tsParticles.setOnClickHandlerpJSDom已加载容器的数组即engine.items引用见 particles.ts 中const pJSDom engine.itemstsParticles.domParticlesmarcbruederlin 风格包装器init、pauseAnimation、resumeAnimation、destroy直接tsParticles.load container 方法在 TS/JS 代码中需要显式引用时const particlesJSCompat globalThis.particlesJS; const pJSDomCompat globalThis.pJSDom; const particlesCompat globalThis.Particles;弃用状态与迁移建议README 的 Deprecation status 明确说明particlesJS、pJSDom、Particles均为 deprecated 兼容 API源码中每个符号都带deprecated this method is obsolete, please use the new tsParticles.xxx注释该包为 obsolete 状态仅维护遗留集成可能在 v5 中被移除强烈建议迁移到直接tsParticlesAPI。仓库中配套了迁移指南 markdown/pjsMigration.md其要点包括把particles.min.js换成tsparticles.min.jsCSS 类.particles-js-canvas-element改为.tsparticles-canvas-elementAPI 映射particlesJS(id, options)→tsParticles.load({ id: id, options })particlesJS.load(id, path, callback)→tsParticles.loadJSON(id, path).then(...)注意loadJSON用 Promise 而非回调选项键名渐进迁移line_linked→links、retina_detect→detectRetina总体上snake_case→camelCase旧键仍可工作控制台会给出警告作为迁移提示。常见陷阱Common pitfalls结合 README 与源码行为使用兼容层时最典型的三类错误未await initPjs(...)就调用 legacy 全局对象—— 三个全局对象及 CDN 的initPjs只有在initPjs执行完成后才存在先调用会得到undefined is not a function期望initPjs返回particlesJS/Particles—— 它的返回类型是Promisevoid兼容对象只能通过globalThisCDN 场景下的裸全局名访问在同一配置对象里混用新旧 tsParticles 选项与旧 particles.js 选项—— 兼容层做的是旧键 → 新键的确定性翻译如speed还要除以 3、bounce变成collisions混写会导致字段被意外覆盖或翻译分支读取到undefined。小结tsparticles/pjs的价值边界非常清晰它让存量 particles.js 代码两种流行 API 风格能以原样的调用方式跑在 tsParticles 引擎上——initPjs负责插件注册与全局对象挂载VincentGarreau/particles.ts负责旧选项到现代选项的逐项翻译含speedFactor 3的速度校准marcbruederlin/Particles.ts提供选择器驱动的Particles.init与播放控制方法。对于新代码正确姿势是直接使用tsParticles.load/tsParticles.loadJSON参考 markdown/pjsMigration.md把本包当作旧站点的过渡期适配器并留意其在 v5 可能被移除的弃用警告。【免费下载链接】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），仅供参考