tsparticles 粒子边界行为move.outModes完全指南配置、取值与源码实现解析【免费下载链接】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 的粒子越界处理选项particles.move.outModes展开说明四条画布边各自的越界行为如何按边独立配置、每种模式值out、destroy、bounce、split等的具体语义并结合tsparticles/engine与tsparticles/updater-out-modes的源码解释越界检测与处理器的底层执行流程。读完本文你可以独立完成按边定制的粒子边界策略例如顶部销毁、底部反弹并理解bounce、split、out等模式在引擎中的真实实现路径。outModes 在配置树中的位置outModes是粒子移动Move选项的一部分完整路径为particles.move.outModes用于控制粒子离开画布边界时发生什么。它支持两种书写形式对象形式按边分别指定行为这是功能最完整的写法字符串简写直接写一个模式值等价于只设置default。这一简写能力可以从引擎源码中得到印证。在 Move.ts 中选项加载逻辑判断outModes是否为对象是对象则逐字段加载否则将其包装为{ default: outModes }处理。因此下面两种配置等价{ particles: { move: { outModes: bounce } } }{ particles: { move: { outModes: { default: bounce } } } }而接口定义 IMove.ts 也明确将类型声明为IOutModes | OutMode | keyof typeof OutMode。按边Per-edge配置outModes对象支持 5 个键允许对四条边分别定制行为其余边回退到default键类型示例说明defaultstringout所有未被单独覆盖的边的默认行为topstringdestroy顶部边的行为bottomstringbounce底部边的行为leftstringnone左侧边的行为rightstringout右侧边的行为这种“按边解析、缺省回退”的机制直接体现在越界更新器的每帧逻辑中。在 OutOfCanvasUpdater.ts 的update()方法里四条边依次用??回退语法取当前边应生效的模式this.#updateOutMode(particle, delta, outModes.bottom ?? outModes.default, OutModeDirection.bottom); this.#updateOutMode(particle, delta, outModes.left ?? outModes.default, OutModeDirection.left); this.#updateOutMode(particle, delta, outModes.right ?? outModes.default, OutModeDirection.right); this.#updateOutMode(particle, delta, outModes.top ?? outModes.default, OutModeDirection.top);也就是说top一旦显式配置顶部越界只看top未配置的边则统一使用default。这正是文档中“defaultapplies to all sides not explicitly overridden”的源码依据。模式值Mode Values全表值行为out粒子从对侧重新进入环绕/循环destroy粒子被移除bounce在边界反弹回画布内bounce-horizontal仅在水平方向边反弹bounce-vertical仅在垂直方向边反弹none不做特殊处理由引擎兜底清理split粒子越界时分裂需要说明取值范围的事实边界当前引擎的枚举定义 OutMode.ts 中定义了 5 个核心枚举成员——bounce、none、out、destroy、split其中split的注释即为 “Split the particle into multiple particles”。bounce-horizontal与bounce-vertical收录在上表来自本仓库 Options 文档但从当前源码结构看它们并未出现在该枚举成员列表中如果你的目标环境以OutMode枚举为准建议以bounce配合bounce.horizontal/bounce.vertical选项来实现分轴反弹见下文“与其他选项的联动”。下面结合源码说明各模式的实际实现。out环绕wrap-aroundout模式实现于 OutOutMode.ts。当粒子从右侧离开画布时它会被传送到左边界之外particle.getRadius()加偏移量反之亦然上下边同理见 OutOutMode.ts 的ParticleOutType.normal分支。一个值得注意的细节是move.warp选项的联动const warp particle.options.move.warp, ... if (direction OutModeDirection.right nextBounds.left canvasSize.width particle.offset.x) { particle.position.x newPos.left; ... if (!warp) { particle.position.y getRandom() * canvasSize.height; ... }即当move.warp为false默认时粒子穿越水平边界后其垂直坐标会被随机化避免粒子沿一条直线“贯穿”屏幕设置为true则保持原始垂直坐标粒子沿直线穿过并从对侧出现。粒子被传送后会置位particle.justWarped true供连接links等插件感知、避免画出一条横穿屏幕的连线。destroy越界销毁DestroyOutMode.ts 逻辑简洁若粒子按当前边与当前模式判断已不在画布内particle.isInsideCanvasForOutMode(outMode, direction)返回 false直接调用particle.destroy(true)将其标记销毁。对于inside型粒子围绕moveCenter运动的粒子只有当其沿速度方向离开中心一定半径后才真正销毁避免误杀仍在中心附近运动的粒子。bounce/split反弹与分裂两者由同一个处理器 BounceOutMode.ts 管理——注意它的modes数组同时包含OutMode.bounce和OutMode.split。实际反弹计算在 Utils.ts 的bounceHorizontal/bounceVertical中仅处理与当前边方向匹配的情况水平函数只处理left/right垂直函数只处理top/bottom只有当粒子“越界”且速度方向确实指向该边时才反弹velocity.x * -newVelocity其中newVelocity取自bounce.horizontal.value垂直方向取bounce.vertical.value。因此该值实际是反弹后的速度保留系数如0.8表示反弹后速度为原来的 80%反弹后粒子位置被钳制回画布内position.x canvasSize.width - size - offset.x等保证粒子不会“卡在墙外”关键差异若模式是split反弹计算完成后额外执行particle.destroy()见 Utils.ts 与 Utils.ts——即“分裂”在实现上表现为按 bounce 规则反弹一次并销毁原粒子由split选项生成的子粒子接管后续表现。此外BounceOutMode构造函数会先收集所有实现了particleBounce的容器插件如 absorbers 等可反弹插件并优先委托给它们处理只有当插件未处理时才执行默认的画布边界反弹。none不处理但会被兜底清理NoneOutMode.ts 并不是完全放任粒子飞走源码中有一层兜底逻辑若move.distance.horizontal/move.distance.vertical已启用粒子沿对应轴做定向移动则跳过兜底交由距离移动逻辑自行管理粒子生命周期未启用 gravity 时粒子必须已经超出“画布加半径”的范围且速度方向仍指向画布外例如向左飞且x -pRadius不成立才会被particle.destroy()启用 gravity 时则根据重力方向gravity.inverse只销毁飞出底边或顶边的粒子实现“受重力影响的粒子落到画布外即消失”这类效果。快速示例Quick example按边混合配置一个完整可复制的示例{ particles: { move: { outModes: { default: out, top: destroy, bottom: bounce } } } }效果解读粒子默认在左右边环绕out一旦触顶top: destroy立即销毁触底bottom: bounce则按bounce.vertical.value系数反弹。由于left/right未显式设置它们回退到default的out。源码级执行流程越界检测是如何每帧运行的将上述碎片串联起来整个越界处理链路如下注册与懒初始化。OutOfCanvasUpdater实现引擎的IParticleUpdater接口见 OutOfCanvasUpdater.ts。init(particle)阶段通过checkOutMode()检查配置中是否用到了bounce/out/destroy/none任一模式用到才创建对应的管理器并存入this.updatersMap——未启用的模式零开销启停条件。isEnabled(particle)要求粒子既未被销毁、也不处于生成中!particle.destroyed !particle.spawning因此正在被发射器/分裂器生成的新粒子不会被越界逻辑干扰每帧分边检测。update()先重置particle.justWarped然后按 bottom → left → right → top 的顺序对每条边取“该边模式 ?? default”把(particle, direction, delta, outMode)分发给所有已注册的管理器管理器按模式过滤。每个管理器在update()开头都执行if (!this.modes.includes(outMode)) return;即每个管理器只响应自己负责的模式天然实现了模式的互斥分发。这一“更新器 可插拔管理器”的结构意味着新增越界行为只需实现IOutModeManager定义见 IOutModeManager.ts并声明自己负责的modes无需修改核心检测循环。与其他选项的联动要点从上述源码可以归纳出几个高频组合bouncebounce.horizontal/bounce.vertical反弹模式本身只决定“是否反弹”反弹后的速度衰减由bounce.*.value控制需要“只在一个轴反弹”时可结合按边配置例如仅左右边设bounce、上下边设out或文档值表中的bounce-horizontal/bounce-vertical以你所使用的版本支持的取值为准outmove.warpwarp: false默认跨边后垂直/水平坐标随机化warp: true保持直线穿越nonemove.distance定向移动粒子通常配none或destroy由距离移动逻辑在到达目标位置后自行销毁nonemove.gravity重力场景下none会在粒子沿重力方向落出画布后兜底销毁。相关文档Move移动选项MoveDestroy销毁选项DestroyOptions 总览Options本文的配置语义与执行流程均以当前仓库的 Options 文档OutModes.md与tsparticles/engine、tsparticles/updater-out-modes源码为准不同发布版本中模式枚举与处理器实现可能存在差异以对应版本的源码与文档为准。【免费下载链接】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），仅供参考