企业官网建设流程全解析

在 Ember 应用中运行 tsParticles 粒子动画 Demo：安装、启动与源码解析

【免费下载链接】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 是一个可高度自定义的 JavaScript 粒子效果库，官方为 React、Vue、Angular、Svelte、Ember 等多种框架提供了现成的组件封装。本文以仓库中的 demo/ember 为例，讲解如何在 Ember 工程中通过@tsparticles/ember封装组件渲染链接粒子、雪花与彩带（confetti）动画，涵盖完整的安装启动流程、package.json 脚本语义、组件用法与底层实现原理。读完本文，你将能够在自己的 Ember 应用中独立接入 tsParticles，并理解其按需初始化引擎、切换配置与主题、加载预设的完整调用链。

Demo 概览：一个组件三种效果

demo/ember是一个独立的 Ember 演示应用（standalone demo），专门用于演示@tsparticles/ember封装组件的用法。它的核心入口是 app/templates/application.hbs，同一页面内通过<Particles>组件同时展示了三种粒子效果：

• 默认的**链接粒子（links）**效果：使用 LINK_OPTIONS 配置，圆形粒子之间绘制白色连线，并开启碰撞；
• **雪花（snow）**效果：通过hash preset="snow"直接以字符串形式引用 @tsparticles/preset-snow 提供的雪花预设，并设置fullScreen=(hash enable=false)关闭全屏模式，使其固定在下方的容器区域内；
• **彩带（confetti）**效果：点击 "Show confetti" 按钮后按条件渲染，使用 CONFETTI_OPTIONS 配置，由 emitters 发射器持续喷射多种颜色的旋转粒子。

演示页还提供 "Switch config"（在链接与雪花配置间切换）和 "Theme"（在default与dark主题间切换）两个按钮，用于演示@options与@theme两个参数的响应式更新能力。

安装与启动：从仓库根目录运行

README 给出的运行方式是从仓库根目录统一使用 pnpm 工作区（workspace）管理依赖。由于@tsparticles/ember、@tsparticles/engine、@tsparticles/preset-snow、tsparticles等均通过workspace:*协议引用（见 demo/ember/package.json），因此必须先在本仓库根目录安装并构建依赖，再进入 demo 目录启动：

pnpm i pnpm run build cd demo/ember pnpm start

其中pnpm run build在仓库根目录执行，用于构建 engine 与各依赖包的产物；pnpm start则启动 Ember 开发服务器。启动成功后，在浏览器中打开http://localhost:4200即可看到粒子动画页面。

脚本语义与运行环境

demo/ember/package.json 中定义了四个脚本，对应pnpm <script>调用：

从源码结构看，该 demo 的 Node 版本要求为14.* || 16.* || >= 18（见 demo/ember/package.json），并使用 TypeScript（typescript、ember-cli-typescript已列为依赖）。测试基础设施方面，testem.js 提供 Testem 配置，配合ember-qunit、qunit-dom与@ember/test-helpers完成组件级测试。

组件调用方式：模板中的<Particles>

<Particles>组件来自@tsparticles/ember封装。其模板实现位于 wrappers/ember/addon/components/particles.hbs，核心是在一个<div>元素上挂载particlesmodifier，并透传四个命名参数：

• @options：粒子配置对象（ISourceOptions），用于控制粒子数量、形状、运动、碰撞、连接线等全部行为；
• @url：可选的 JSON 配置文件地址，与@options二选一，最终都会传给tsParticles.load()；
• @particlesLoaded：容器加载完成后的回调函数；
• @theme：主题名称字符串，加载完成后通过container.loadTheme(theme)动态切换主题。

Demo 中的应用层调用如下（见 app/templates/application.hbs）：

<Particles class="fixed-size-particles" @options={{this.options}} @theme={{this.theme}} @particlesLoaded={{this.loadedCallback}} /> <Particles class="fixed-size-snow" @options={{hash preset="snow" fullScreen=(hash enable=false)}} />

注意雪花组件的写法：@options可以直接传一个内联hash，其中preset字段指定要加载的预设名称，这说明@tsparticles/ember与 tsParticles 引擎的选项体系完全一致——预设名同样通过 options 下发。

控制器逻辑：引擎初始化、配置切换与主题切换

演示应用的状态逻辑集中在 app/controllers/application.ts，它是理解整套调用链的关键：

1. 按需初始化引擎：在构造函数中，仅当typeof window !== "undefined"（客户端环境）时调用initParticlesEngine，并在回调中同时注册loadFull(engine)（加载全部功能）与loadSnowPreset(engine)（注册 snow 预设）。源码注释明确说明这是为了兼容 Ember 的 FastBoot 服务端渲染场景——服务端没有window/document，因此必须将引擎初始化延迟到客户端运行时。
2. 响应式状态：@tracked装饰器（来自@glimmer/tracking）标记的options、theme、isConfettiVisible一旦变化，模板会自动重渲染并将新值传入<Particles>。
3. 配置切换：switchConfig在LINK_OPTIONS与SNOW_OPTIONS两个配置对象之间轮流切换，可直观验证组件对@options变化的响应。
4. 主题切换：toggleTheme在default与dark之间切换this.theme，配合@theme参数触发loadTheme。

其中loadedCallback接收一个Container参数（即 tsParticles 的容器实例），在 Demo 中打印一条日志，可用于调试或获取粒子实例执行高级操作。

源码解析：modifier 与引擎初始化工具

Particles modifier 的加载流程

组件底层的实际逻辑在 wrappers/ember/addon/modifiers/particles.ts。ParticlesModifier.modify的执行流程揭示了引擎与容器的完整生命周期：

1. 先await waitForParticlesEngineInitialization()，确保引擎已完成初始化；
2. 检查isParticlesEngineInitialized()，若未初始化则抛出明确错误：initParticlesEngine(...) must be called once before rendering <Particles /> components.——这提醒开发者：使用<Particles>前必须至少调用一次initParticlesEngine；
3. 销毁旧容器（this.#container?.destroy()），避免重复渲染时泄漏；
4. 调用tsParticles.load({ id: element.id, options: options ?? {}, url })创建新容器，其中容器 id 直接使用组件的 DOM id（模板中通过unique-id-polyfillhelper 生成唯一 id）；
5. 若传了theme，则调用container.loadTheme(theme)应用主题；
6. 若传了particlesLoaded回调，则把容器实例回传给调用方；
7. 通过registerDestructor注册销毁钩子，在组件销毁时自动container.destroy()，保证内存安全。

initParticlesEngine 的单例语义

wrappers/ember/addon/utils/init-particles-engine.ts 提供了幂等的引擎初始化工具：

• initParticlesEngine(init?)：接收一个可选的注册回调（类型为ParticlesPluginRegistrar），在回调中调用engine上的各loadXxx函数注册预设/插件，随后执行tsParticles.init()；
• 模块内部用initialized、initPromise、initCallback三个变量保证整个应用生命周期内只初始化一次；若重复传入不同的回调，会抛出错误要求回调保持稳定；
• 另导出isParticlesEngineInitialized()与waitForParticlesEngineInitialization()两个辅助函数，供 modifier 等内部模块同步等待初始化完成。

三种配置的实战解读

三个配置对象完整位于 app/utils/options.ts，这里给出关键参数的含义与取值，方便你按需复制改造。

LINK_OPTIONS：链接粒子

SNOW_OPTIONS：雪花效果

在链接配置基础上做了三点关键改动：fullScreen.zIndex: -1让画布置于页面背景层；particles.number.value: 400大幅提高粒子密度；move.direction: "bottom"让粒子只向下飘落，并启用wobble（摆动）参数distance: 10、speed: 10模拟雪花摇曳下落。

CONFETTI_OPTIONS：彩带效果

这是三者中最复杂的一份配置，核心在于：

• emitters发射器：位置固定在{x: 50, y: 100}（即屏幕底部中央），以rate: { quantity: 5, delay: 0.15 }的速率每次喷射 5 个粒子；
• 粒子颜色数组["#1E00FF", "#FF0061", "#E1FF00", "#00FF9E"]提供四色随机；
• move.gravity.enable: true开启重力，decay: 0.05让速度逐渐衰减，outModes: { top: "none", default: "destroy" }表示粒子飞出屏幕（除顶部）后销毁；
• rotate、tilt、roll、wobble四项动画参数共同营造彩带翻飞、旋转的立体感；
• size.animation使用startValue: "min"、count: 1、speed: 16、sync: true让尺寸从最小值同步放大；
• 最后通过responsive数组声明在maxWidth: 1024（平板及以下）时将粒子速度降低到{ min: 33, max: 66 }，实现响应式降载。

与官方 wrapper 测试的呼应

@tsparticles/ember封装自带完整的测试套件，位于 wrappers/ember/tests，包括integration/components/particles-test.ts（组件集成测试）、helpers/particles.ts（测试辅助）以及使用 QUnit 的单元测试，配合 wrappers/ember/config/ember-try.js 的 ember-try 多版本矩阵。如果你要扩展 demo 或封装新组件，可参照这些测试文件验证<Particles>的行为是否符合预期。

小结

通过demo/ember这份独立演示应用，可以快速掌握在 Ember 中使用 tsParticles 的完整链路：pnpm workspace 安装与构建 →ember serve启动 →<Particles>组件消费@options/@theme/@particlesLoaded→initParticlesEngine按需注册引擎与预设 → modifier 内部完成容器加载、主题切换与销毁。你可以直接复制 options.ts 中的三份配置作为起点，在此基础上调整颜色、数量、速度与动画参数，打造属于自己的 Ember 粒子背景。

【免费下载链接】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