tsParticles 喷泉预设（Fountain Preset）实战指南：从快速接入到源码级参数定制-平芜编程栈

tsParticles 喷泉预设（Fountain Preset）实战指南：从快速接入到源码级参数定制

【免费下载链接】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 的 Fountain（喷泉）预设用于创建"随机位置喷出的彩色粒子、落地即破碎"的喷泉式粒子效果，常作为网页动态背景或页面装饰。本文以仓库内 presets/fountain/README.md 为主线，结合预设源码与默认配置，完整讲解安装接入、CDN 引入、自定义选项、依赖结构与常见踩坑点，读完后你可以在任何 tsParticles 项目中一键复现并深度定制喷泉效果。

喷泉预设的核心机制

Fountain 预设并非简单"让粒子向下掉落"，而是组合了多个底层能力实现的复合效果。从默认配置源码可以还原它的完整工作原理：

由 Emitters 插件持续喷射粒子：粒子初始数量为 0（number.value: 0），全部由发射器按固定速率生成，方向为顶部（direction: "top"），每 0.1 秒喷射 5 个；
重力作用下的抛射运动：粒子开启重力（gravity.enable: true），配合 10~20 的初速度，形成"向上喷出、受重力回落"的抛物线轨迹；
落地即破碎（split）：outModes.bottom设置为split，粒子触底后分裂为 2 个碎片，碎片以 1.1~2 倍尺寸因子继续下落，直到被 Destroy 更新器移除；
拖尾（trail）渲染：启用trail插件留下长度为 3 的持久拖影，强化水流喷射的视觉连续性；
油漆（paint）着色：填充 9 种预设颜色（蓝、青、绿、黄、橙、红、玫红、紫），使喷泉色彩缤纷。

这些能力的装配由 loadFountainPreset 完成：它一次性注册@tsparticles/basic基础运行时、updater-destroy销毁更新器、plugin-emitters发射器插件与plugin-trail拖尾插件，并将内置options注册为名为fountain的预设。

快速开始：三步接入

官方 README 给出三条必须遵守的步骤：

安装@tsparticles/engine（或直接使用下方的 CDN bundle）；
在调用tsParticles.load(...)之前先调用loadFountainPreset(tsParticles)；
在 options 中设置preset: "fountain"。

CDN / Vanilla JS / jQuery 方式

直接引入预构建的 bundle 脚本，无需手动装包：

<script src="https://cdn.jsdelivr.net/npm/@tsparticles/preset-fountain@4/tsparticles.preset.fountain.bundle.min.js"></script>

脚本加载完成后即可初始化：

(async () => { await loadFountainPreset(tsParticles); await tsParticles.load({ id: "tsparticles", options: { preset: "fountain", }, }); })();

从 bundle 入口源码可以看到，该 bundle 同时把tsParticles引擎实例与loadFountainPreset挂到全局对象上，因此浏览器环境中可以直接使用这两个全局变量。

npm / 模块化方式

使用包管理器安装依赖：

npm install @tsparticles/engine @tsparticles/preset-fountain

在入口文件中加载并初始化：

import { tsParticles } from "@tsparticles/engine"; import { loadFountainPreset } from "@tsparticles/preset-fountain"; (async () => { await loadFountainPreset(tsParticles); await tsParticles.load({ id: "tsparticles", options: { preset: "fountain", }, }); })();

如果希望进一步压缩首屏体积，可以使用懒加载入口：@tsparticles/preset-fountain/lazy。对应实现见 index.lazy.ts，它通过动态import()按需加载 basic、emitters、trail、destroy 等依赖，仅在loadFountainPreset真正被调用时才拉取相关代码。

默认参数全解析

预设的所有默认行为都定义在 options.ts 中。了解这些默认值，是后续定制的基础：

配置项	默认值	作用
`fpsLimit`	`120`	帧率上限
`particles.number.value`	`0`	初始粒子数为 0，全部由发射器生成
`particles.bounce.vertical.value`	`min: 0.75, max: 0.85`	粒子触底反弹（垂直方向）的弹性系数范围
`particles.paint.fill.color.value`	9 种颜色数组	填充粒子颜色（蓝/青/绿/黄/橙/红/玫红/紫），`enable: true`开启
`particles.size.value`	`min: 10, max: 20`	粒子尺寸范围
`particles.opacity.value`	`0.5`	粒子不透明度
`particles.destroy.mode`	`"split"`	销毁模式为分裂；`count: 2`每粒子分裂 2 个，`factor`为 1.1~2 倍，`rate`为 2~3
`particles.move.enable`	`true`	开启运动
`particles.move.gravity`	`enable: true, maxSpeed: 50`	开启重力，最大下落速度 50
`particles.move.speed`	`min: 10, max: 20`	喷射初速度范围
`particles.move.outModes`	`bottom: "split"`,`default: "bounce"`,`top: "none"`	底部出界分裂、默认反弹、顶部出界不处理
`detectRetina`	`true`	自动启用 Retina 高分辨率渲染
`background.color`	`"#fff"`	白色背景
`emitters.direction`	`"top"`	粒子向上喷射
`emitters.life`	`count: 0, duration: 0.15, delay: 3`	发射器无限循环，单次持续 0.15 秒、间隔 3 秒
`emitters.rate`	`delay: 0.1, quantity: 5`	每 0.1 秒发射 5 个粒子
`emitters.size`	`width: 0, height: 0`	点状发射源
`trail.enable`	`true`	开启拖尾
`trail.fill.color`	`"#fff"`	拖尾填充色（与背景一致，形成渐隐效果）
`trail.length`	`3`	拖尾长度

注意一个值得留意的设计：默认particles.number.value为 0，说明所有粒子完全由 Emitters 生成，这也解释了为什么"覆盖emitters配置会直接改变甚至破坏默认喷泉行为"（详见下文常见陷阱）。

自定义喷泉效果

Fountain 预设完全复用 tsParticles 的标准 options 机制：你可以像配置普通 tsParticles 实例一样覆盖任意属性，未覆盖的属性继续沿用预设默认值。

例如，把圆形粒子替换为方形：

tsParticles.load({ id: "tsparticles", options: { particles: { shape: { type: "square", // 自 v2 起，使用方形需要额外加载 square shape 包 }, }, preset: "fountain", }, });

预设之外的选项与preset同时存在时，两者会合并，用户的显式配置优先生效。基于此可以自由调整喷泉的"节奏"与"外观"，例如：

修改emitters.rate.delay与emitters.rate.quantity，控制喷水密度；
修改emitters.life.duration与emitters.life.delay，控制喷泉的间歇喷射节奏；
修改particles.move.speed与particles.move.gravity.maxSpeed，调整喷射高度与下落速度；
修改particles.paint.fill.color.value颜色数组，切换配色主题；
修改particles.destroy.split.count、factor、rate，改变落地破碎的碎片数量与大小。

需要提醒的是：覆盖粒子 shape 时，必须同时加载对应的 shape 包（例如方形需要@tsparticles/shape-square），否则粒子不会渲染。仓库 shapes 目录中列出了全部可用形状。

在框架组件库中使用

tsParticles 为 React、Vue 2/3、Angular、Svelte、jQuery、Preact、Inferno、Solid、Riot、Web Components 等提供了现成组件库。使用方式一致：在组件初始化处调用loadFountainPreset替代loadFull/loadSlim等函数，然后照常传入包含preset: "fountain"的 options。上文所有 options 写法在各类组件库中同样有效，相关组件实现可参考仓库 wrappers 目录下对应框架的源码。

依赖关系一览

Fountain 预设由以下包组合而成（见 package.json 的dependencies）：

包	在该预设中的角色	仓库内参考
`@tsparticles/basic`	预设使用的基础运行时 bundle	bundles/basic/README.md
`@tsparticles/engine`	tsParticles 引擎与预设注册机制	engine/README.md
`@tsparticles/plugin-emitters`	从可配置发射器喷射粒子	plugins/emitters
`@tsparticles/plugin-trail`	提供持久画布拖尾渲染	plugins/trail
`@tsparticles/updater-destroy`	粒子阶段结束（分裂/销毁）时移除粒子	updaters/destroy

从源码看，loadFountainPreset内部通过Promise.all并行调用loadBasic、loadDestroyUpdater、loadEmittersPluginSimple、loadTrailPlugin，全部完成后再注册预设，确保tsParticles.load执行时所需能力都已就绪。这正对应官方 README 强调的"必须先调用loadFountainPreset再load"这一顺序约束。

架构关系图

预设、插件、更新器与 bundle 之间的组装关系如下（整理自 README 中的结构说明）：

常见陷阱

官方 README 明确列出了三个最容易出错的地方，结合源码可以进一步理解其根因：

在loadFountainPreset(tsParticles)之前就调用tsParticles.load(...)：由于预设的注册发生在异步的pluginManager.register回调中（见 index.ts），提前load会因找不到fountain预设而失败或回退到无效果；
修改粒子 shape 却没有加载对应的 shape 包：例如把shape.type改为"square"却未引入 square 形状模块，粒子将不会显示（自 v2 起形状与核心分离，需要按需加载）；
覆盖emitters配置会替换掉默认喷泉行为：因为默认粒子数（number.value）为 0，粒子完全依赖发射器生成，改写emitters等于重写整个喷泉的供给逻辑，建议在充分理解发射器选项（direction、rate、life、size）后再做调整。

小结

Fountain 预设是理解 tsParticles"预设 + 插件 + 更新器"组合机制的一个很好的范例：一个看似简单的喷泉效果，背后是发射器喷射、重力抛射、落地分裂销毁与拖尾渲染的协同工作。掌握默认配置中的每个参数，再结合标准 options 覆盖机制，就能在几行代码内做出完全符合自己页面气质的喷泉粒子背景。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考