tsParticles External Particle Interaction 插件在鼠标/点击位置生成自定义粒子的实现与配置详解【免费下载链接】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/interaction-external-particle交互插件展开介绍它如何通过 CDN、ESM/CommonJS 三种方式接入如何把particle模式挂到onHover/onClick事件上以及pauseOnStop、stopDelay、replaceCursor、options四个核心参数的确切行为。读完并结合仓库源码后你可以直接在项目中复现“鼠标划过留下一个跟随光标的粒子、点击生成粒子”的交互效果并理解插件内部的粒子生成、销毁与延时清理机制。插件定位一个“外部交互”External Interaction插件tsparticles/interaction-external-particle是 tsParticles 交互插件族中的一员官方定位是“interaction plugin for particle effect around mouse or HTML elements”即让粒子效果出现在鼠标或 HTML 元素周围。与其他外部交互bubble、repulse、attract等“作用于已有粒子”的模式不同particle模式属于“生成型”交互它在光标位置额外创建一个独立的粒子该粒子的外观由你单独配置的粒子选项决定与画布上主粒子群的选项互不干扰。从源码结构看该插件只有一个核心类InteractivityParticleMaker继承自tsparticles/plugin-interactivity提供的ExternalInteractorBase插件的全部行为都集中在这个类里见 InteractivityParticleMaker。插件包的元信息版本 4.3.3、peer 依赖等见 package.json其 README 原文见 interactions/external/particle/README.md。接入前的必备清单Quick checklistREADME 给出的接入步骤可以归纳为三步这三步的顺序是硬性要求安装tsparticles/engine或使用 CDN 全家桶在调用tsParticles.load(...)之前调用本包的 loader 函数以及交互基础设施插件loadInteractivityPlugin在tsParticles.load(...)的配置中应用本插件的选项见下文“选项映射”一节。之所以第 2 步必须放在load之前是因为 loader 做的事情是把InteractivityParticleMaker注册到引擎的插件管理器中。从 index.ts 可以看到export async function loadExternalParticleInteraction(engine: Engine): Promisevoid { engine.checkVersion(__VERSION__); await engine.pluginManager.register((e: InteractivityEngine) { ensureInteractivityPluginLoaded(e); e.pluginManager.addInteractor?.(externalParticle, container { return Promise.resolve(new InteractivityParticleMaker(container)); }); }); }两个关键点ensureInteractivityPluginLoaded(e)强制要求tsparticles/plugin-interactivity已加载因此loadInteractivityPlugin(tsParticles)必须先行addInteractor(externalParticle, ...)以externalParticle为键注册交互器工厂。之后每当particle模式被事件触发时引擎会用容器实例化InteractivityParticleMaker。另外仓库还提供了懒加载入口 index.lazy.ts对应 npm 包的./lazy子路径它在注册时才动态import(./InteractivityParticleMaker.js)适合按需加载以减小首屏体积浏览器端的全局挂载逻辑见 browser.ts它会把loadExternalParticleInteraction挂到globalThis上这就是 CDN 场景下能直接调用全局函数的原因。三种接入方式方式一CDN / Vanilla JS / jQueryCDN 或纯 HTML 场景下需要引入tsparticles.interaction.external.particle.min.js这个文件它会向全局导出loadExternalParticleInteraction;加载脚本后即可按如下方式初始化与 README 中的官方示例一致(async () { await loadInteractivityPlugin(tsParticles); await loadExternalParticleInteraction(tsParticles); await tsParticles.load({ id: tsparticles, options: {/* options */}, }); })();方式二ESM 模块$ npm install tsparticles/interaction-external-particle或$ yarn add tsparticles/interaction-external-particleimport { tsParticles } from tsparticles/engine; import { loadInteractivityPlugin } from tsparticles/plugin-interactivity; import { loadExternalParticleInteraction } from tsparticles/interaction-external-particle; (async () { await loadInteractivityPlugin(tsParticles); await loadExternalParticleInteraction(tsParticles); })();方式三CommonJSconst { tsParticles } require(tsparticles/engine); const { loadInteractivityPlugin } require(tsparticles/plugin-interactivity); const { loadExternalParticleInteraction } require(tsparticles/interaction-external-particle); (async () { await loadInteractivityPlugin(tsParticles); await loadExternalParticleInteraction(tsParticles); })();三种方式的公共依赖是一致的从 package.json 的peerDependencies可以看到本包硬性依赖tsparticles/engine和tsparticles/plugin-interactivity两个 workspace 包。若使用tsparticles/slim及以上的 CDN 全家桶interactivity 插件已内置可省掉loadInteractivityPlugin一步裸装tsparticles/engine时则两者缺一不可。选项映射particle模式如何被事件触发README 中的“Option mapping”一节明确了本插件的两个配置键位这是使用时最容易被忽视的部分事件键interactivity.events.onHover.mode或interactivity.events.onClick.mode取值particle模式选项键interactivity.modes.particle。最小可用配置{ interactivity: { events: { onHover: { enable: true, mode: particle } }, modes: { particle: {} } } }如果想让点击也生成粒子把onClick同样配置即可mode支持数组可同时命中多个模式{ interactivity: { events: { onHover: { enable: true, mode: particle }, onClick: { enable: true, mode: particle } }, modes: { particle: {} } } }触发判定逻辑就在 InteractivityParticleMaker.ts 的isEnabled方法 中可以精确对应到配置语义return ( !!events ((mouse.clicking mouse.inside !!mouse.position isInArray(particleMode, events.onClick.mode)) || (mouse.inside !!mouse.position isInArray(particleMode, events.onHover.mode))) );即onClick分支要求“正在点击 鼠标在容器内 有位置 onClick.mode数组包含particle”onHover分支只要求“鼠标在容器内 有位置 onHover.mode包含particle”。注意events优先取粒子级的particle.interactivity覆写否则回退到全局options.interactivity。modes.particle的四个参数默认值与源码级语义选项类定义见 InteractivityParticleOptions接口定义见 IInteractivityParticleOptions。四个参数及默认值如下参数类型默认值说明options粒子选项RecursivePartialIParticlesOptions无用于生成“交互粒子”的外观选项颜色、形状、大小等与主粒子群配置隔离pauseOnStopbooleanfalse鼠标停止移动时暂停粒子实际是启动延时销毁计时器见下文replaceCursorbooleanfalse用生成的粒子替换系统光标隐藏光标stopDelaynumber0毫秒鼠标停止后、粒子被销毁前的延时逐项结合源码看它们的实际行为options独立的一套粒子外观在interact方法中真正创建粒子的代码是const particleOptions deepExtend(interactivityParticleOptions.options, { move: { enable: false, }, }) as RecursivePartialParticlesOptions; this.#particle container.particles.addParticle(this.#lastPosition, particleOptions);两点值得注意传入的是interactivityParticleOptions.options即modes.particle.options不是画布主配置particles——所以交互粒子可以拥有完全不同的颜色、形状和尺寸源码强制叠加了move.enable: false意味着无论你在options.move里怎么写交互粒子自身都不会运动它只会跟随光标位置被逐帧搬运见下文“位置搬运”。一个典型配置示例生成一个跟随光标的彩色圆点{ interactivity: { events: { onHover: { enable: true, mode: particle } }, modes: { particle: { pauseOnStop: true, stopDelay: 500, replaceCursor: true, options: { color: { value: [#ff3300, #402243] }, opacity: { value: 0.8 }, size: { value: 10 }, shape: { type: circle } } } } } }replaceCursor隐藏光标让粒子“变成”指针当replaceCursor为true时粒子创建的同时会把目标元素的cursor设为none作用对象是交互容器对应的HTMLElement若是Window/Document则作用于document.body粒子销毁时再把cursor还原为空字符串。源码见 InteractivityParticleMaker.ts 中 replaceCursor 的两处分支。这解释了为什么该参数适合做“自定义光标”效果粒子本身不运动move.enable: false但每一帧都被强制对齐到鼠标坐标this.#particle.position.x this.#lastPosition.x视觉等效于一个可自定义外观的鼠标指针。pauseOnStopstopDelay延时销毁机制这两个参数配合实现了“鼠标停住 → 延时 → 粒子消失”的行为。interact中先比较当前鼠标坐标与上一帧坐标#lastPosition若完全一致且pauseOnStop为true视为mouseStopped随后this.#clearTimeout setTimeout(() { if (!this.#particle) return; // 还原光标如果 replaceCursor 开启 this.#particle.destroy(true); this.#particle undefined; }, clearDelay);即stopDelay毫秒后销毁粒子并还原光标若鼠标再次移动会先clearTimeout取消这次销毁、继续搬运现有粒子。stopDelay默认为0表示鼠标一停下一帧就销毁pauseOnStop默认为false表示不做停止检测、粒子常驻跟随直到clear()。一次交互的完整生命周期把interact方法串起来可以梳理出particle模式每一帧的完整流程前置检查容器不存在retina.reduceFactor或actualOptions.interactivity.modes.particle未配置时直接返回记录坐标把当前鼠标坐标存入#lastPosition无坐标时返回停止检测若命中mouseStopped启动/维持stopDelay延时销毁计时器后返回取消旧计时若鼠标在动先清除可能挂起的销毁计时器创建粒子#particle不存在时用modes.particle.options叠加move.enable: false在鼠标位置调用container.particles.addParticle创建replaceCursor开启时同步隐藏光标位置搬运每帧把粒子的position.x/y直接赋值为鼠标坐标实现“吸附跟随”。此外该类声明了readonly maxDistance 0clear()、init()、reset()均为空实现——结合maxDistance的含义可以推断该模式不受“影响半径”限制它本就不作用于已有粒子引擎在交互器重置时的通用清理也不会影响它持有的粒子销毁完全由上面的延时逻辑负责。常见坑Common pitfalls与排障建议README 列出的三条排障经验结合源码可以给出更具体的解释tsParticles.load(...)先于loadInteractivityPlugin(...)/loadExternalParticleInteraction(...)调用loader 是通过engine.pluginManager.register延迟注册的但particle模式必须依赖已注册的externalParticle交互器和plugin-interactivity基础设施顺序颠倒时事件命中particle模式却找不到对应交互器表现为配置了却不生成粒子。启用高级选项前先核对 peer 依赖tsparticles/engine与tsparticles/plugin-interactivity是 peerDependencies见 package.json缺失其一会直接抛加载错误。一次只改一组选项particle模式的配置面包含events何时触发、modes.particle.options粒子长什么样、pauseOnStop/stopDelay何时消失、replaceCursor是否替换光标四个相对独立的维度分组修改可以快速定位回归。若配置了onHover.mode: particle但看不到粒子可依次检查鼠标是否真正在容器内isEnabled要求mouse.inside、modes.particle是否声明哪怕空对象、modes.particle.options的颜色/尺寸是否可见透明色或 0 尺寸不会报错但不可见。延伸仓库中可继续深入的入口插件 README 与本文依据的原始文档interactions/external/particle/README.md交互器核心实现interactions/external/particle/src/InteractivityParticleMaker.ts注册入口标准 / 懒加载 / 浏览器全局index.ts、index.lazy.ts、browser.ts选项类与接口InteractivityParticleOptions.ts、IInteractivityParticleOptions.ts引擎侧交互文档interactivity总览、事件与模式markdown/Options/Interactivity.md、markdown/Options/Interactivity/Events.md、markdown/Options/Interactivity/Modes.mdmarkdown/Options/Interactivity/Modes.md中还收录了push点击在光标附近添加粒子等相近模式可与本插件的particle模式对照push是在主粒子群参数基础上“追加粒子”而particle是用独立选项生成一个专属粒子两者适用场景不同选型时可据此区分。【免费下载链接】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），仅供参考
