tsParticles 粒子斥力交互插件 @tsparticles/interaction-particles-repulse：安装配置与源码级实现解析

tsParticles 粒子斥力交互插件 tsparticles/interaction-particles-repulse安装配置与源码级实现解析【免费下载链接】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 仓库中的粒子间斥力Repulse交互插件展开介绍tsparticles/interaction-particles-repulse的安装与加载方式、particles.repulse配置项的完整用法并结合仓库源码剖析Repulser交互器如何基于网格查询与距离衰减公式在每帧内驱动粒子相互排斥读完后可独立完成该效果的接入与参数调优。插件定位与快速接入清单斥力交互插件是一个**粒子对粒子particle-to-particle**的自动交互开启后每个启用斥力的粒子会在其作用半径内推开其他粒子无需鼠标等外部交互触发常用于模拟流体感、气泡群、群体避让等动画背景。它属于 tsParticles 交互插件体系依赖交互系统插件tsparticles/plugin-interactivity提供的粒子交互调度机制见 InteractionManager。按 README 的快速清单接入只需三步安装tsparticles/engine或使用 CDN 版本在调用tsParticles.load(...)之前先调用本包的加载函数并先加载交互插件在tsParticles.load(...)的options中应用本插件的选项键particles.repulse。接入方式一CDN / Vanilla JS / jQueryVanilla 版本的 CDN 脚本中斥力交互对应一个必需的 JS 文件tsparticles.interaction.particles.repulse.min.js引入该文件后它会导出一个用于加载交互插件的函数loadParticlesRepulseInteraction脚本加载完成后的典型用法(async () { await loadInteractivityPlugin(tsParticles); await loadParticlesRepulseInteraction(tsParticles); await tsParticles.load({ id: tsparticles, options: {/* options */}, }); })();注意执行顺序loadInteractivityPlugin(tsParticles)必须先于tsParticles.load(...)完成。源码层面这一依赖是硬性校验的——插件注册时会调用ensureInteractivityPluginLoaded(e)在交互插件未加载的情况下抛出错误见 index.ts。接入方式二ESM / CommonJS通过 npm 或 yarn 安装$ npm install tsparticles/interaction-particles-repulse或$ yarn add tsparticles/interaction-particles-repulseCommonJS 引入方式const { tsParticles } require(tsparticles/engine); const { loadInteractivityPlugin } require(tsparticles/plugin-interactivity); const { loadParticlesRepulseInteraction } require(tsparticles/interaction-particles-repulse); (async () { await loadInteractivityPlugin(tsParticles); await loadParticlesRepulseInteraction(tsParticles); })();ESM 引入方式import { tsParticles } from tsparticles/engine; import { loadInteractivityPlugin } from tsparticles/plugin-interactivity; import { loadParticlesRepulseInteraction } from tsparticles/interaction-particles-repulse; (async () { await loadInteractivityPlugin(tsParticles); await loadParticlesRepulseInteraction(tsParticles); })();加载完成后可再调用tsParticles.load({...})传入选项配置。包名、版本与发布产物定义见 package.json。插件注册流程loadParticlesRepulseInteraction做了什么阅读 index.ts 可以确认完整的注册链路export async function loadParticlesRepulseInteraction(engine: Engine): Promisevoid { engine.checkVersion(__VERSION__); await engine.pluginManager.register((e: InteractivityEngine) { ensureInteractivityPluginLoaded(e); e.pluginManager.addInteractor?.(particlesRepulse, container { return Promise.resolve(new Repulser(container)); }); }); }关键点engine.checkVersion(__VERSION__)构建时注入的__VERSION__用于与当前引擎版本做兼容性校验ensureInteractivityPluginLoaded(e)校验tsparticles/plugin-interactivity已注册未注册则直接报错addInteractor(particlesRepulse, ...)向交互插件管理器注册一个名为particlesRepulse的粒子交互器工厂运行时由交互系统按容器container实例化出Repulser对象。也就是说本包本身不包含粒子渲染与帧循环逻辑它只是向引擎的插件管理器挂了一个交互器真正的每帧调度由交互系统统一驱动。选项映射particles.repulse完整配置选项主键为particles.repulse即Interactivity Particles repulse节点最简开启配置{ particles: { repulse: { enable: true } } }完整字段说明以 官方选项文档 和选项类 ParticlesRepulse.ts 为准键类型源码默认值说明enablebooleanfalse是否启用斥力行为关闭时交互器不会对该粒子生效distancenumber/ range1斥力作用距离半径实际生效值会乘以视网膜像素比container.retina.pixelRatiodurationnumber/ range1文档中定义为效果持续时间秒factornumber/ range1斥力强度系数与speed相乘后构成作用速度speednumber/ range1位移速度越大粒子被推得越快、越远除布尔开关外distance、duration、factor、speed均为RangeValue类型即除单一数值外还支持{ min: x, max: y }这样的区间随机取值形式每个粒子的实际值会在区间内随机抽取区间解析由getRangeValue完成。选项类通过loadRangeProperty加载这些字段见 ParticlesRepulse.ts。一个包含区间值的完整示例{ repulse: { enable: true, distance: 120, duration: 1.5, factor: 1, speed: 80, value: { min: 20, max: 60 } } }示例中value区间写法沿用官方选项文档的演示见 Repulse.md。从当前源码看interact()实际参与位移计算的是distance、speed、factor三个区间值。源码级实现解析Repulser交互器如何逐帧排斥粒子核心逻辑全部位于 Repulser.ts。Repulser继承交互系统基类ParticlesInteractorBase对外暴露四个关键方法。生效条件isEnabledisEnabled(particle: RepulseParticle): boolean { return particle.options.repulse?.enabled ?? false; }判定是逐粒子进行的只有该粒子自身选项里repulse.enabled为true时它才会参与斥力交互。这意味着可以通过粒子组的差异化选项如按颜色分组配置让部分粒子带斥力、部分不带。交互系统的调度入口在 InteractionManager每帧粒子更新阶段管理器遍历所有已注册的粒子交互器对每个粒子依次调用isEnabled(particle)与interact(particle, ...)。因此粒子间自动交互不需要任何鼠标事件驱动属于interactParticle阶段内的自动行为。作用半径初始化视网膜适配与最大距离统计interact()首次处理某粒子时会做一次性初始化见 Repulser.tsp1.repulse { distance: repulseDistance * container.retina.pixelRatio, speed: getRangeValue(repulseOpt1.speed), factor: getRangeValue(repulseOpt1.factor), };作用半径按pixelRatio放大保证在 Retina/高分屏上视觉上的作用范围与配置值一致getRangeValue将区间配置解析为具体随机值speed与factor各取一次同时用if (repulseDistance this.maxDistance)维护本容器的#maxDistance供外部读取当前场景中最远的斥力半径。排斥位移计算网格查询 距离衰减每帧对每个启用的粒子p1见 Repulser.tsconst pos1 p1.getPosition(), query container.particles.grid.queryCircle(pos1, p1.repulse.distance), p1DistanceFactor identity / p1.repulse.distance; for (const p2 of query) { if (p1 p2 || p2.destroyed) { continue; } const pos2 p2.getPosition(), { dx, dy, distance } getDistances(pos2, pos1), distanceFactor identity / distance, velocity p1.repulse.speed * p1.repulse.factor; if (distance minDistance) { const repulseFactor clamp((identity - Math.pow(distance * p1DistanceFactor, squareExp)) * velocity, minVelocity, velocity) * distanceFactor; this.#normVec.x dx * repulseFactor; this.#normVec.y dy * repulseFactor; p2.position.addTo(this.#normVec); } else { ... } }可以拆解为四个要点空间索引加速container.particles.grid.queryCircle(pos1, distance)只取斥力半径内的候选粒子避免 O(n²) 全量两两比较这是大量粒子场景下斥力效果仍可实时的关键衰减曲线1 - (distance / maxDistance)²squareExp为平方指数决定了离得越近推得越狠——距离趋近 0 时因子趋近 1到达半径边缘时衰减为 0强度控制位移速度velocity speed × factor最终再经clamp(..., minVelocity, velocity)限制在[minVelocity, velocity]区间然后除以距离归一化方向向量(dx, dy)位移作用对象注意位移是加在对方粒子p2上的p2.position.addTo(...)即p1的斥力场把半径内其他粒子推开当两者距离小于极小阈值minDistance时退化为直接按velocity做轴向位移防止除零和完全重合。RepulseParticle类型Repulser.ts为每个粒子挂载了{ distance, factor, speed }的运行期缓存初始化后不再重复解析区间值。另外从源码看选项类中声明的duration字段在interact()的位移公式里并未被直接引用当前实现的效果持续时间主要由粒子自身生命周期与后续帧的连续位移共同体现调参时应以distance/speed/factor为主。常见问题排查以下问题在 README 的 Common pitfalls 中明确列出调用顺序错误在loadInteractivityPlugin(...)之前调用tsParticles.load(...)——斥力依赖交互系统的帧内调度缺少它时particles.repulse配置不会生效依赖包缺失启用高级选项前先确认必需的 peer 包已安装本插件要求tsparticles/engine与tsparticles/plugin-interactivity逐项排查法一次只改一个选项组比如只调distance以便快速定位参数回归。相关文件索引文件作用interactions/particles/repulse/README.md插件接入说明CDN/ESM/CommonJS 与选项映射interactions/particles/repulse/src/index.ts插件加载函数与交互器注册interactions/particles/repulse/src/Repulser.ts斥力交互器核心算法interactions/particles/repulse/src/Options/Classes/ParticlesRepulse.ts选项类与默认值interactions/particles/repulse/src/Options/Interfaces/IParticlesRepulse.ts选项接口定义markdown/Options/Particles/Repulse.mdparticles.repulse字段表与示例plugins/interactivity/src/InteractionManager.ts粒子交互器的每帧调度入口【免费下载链接】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），仅供参考