企业官网建设流程全解析

tsParticles cosmic-radiation 调色板：从快速应用到源码级注册机制的完整指南

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

本篇以仓库中的 cosmic-radiation 调色板文档 为主体，完整继承其色板定义、安装清单与 CDN/组件两种用法，并结合 options.ts、index.ts 等源码以及引擎侧的 Options.ts 实现，讲清调色板“只定义颜色、不定义行为”的设计边界，以及palette配置项在引擎加载管线中是如何被解析和消费的。读完后你可以把这个深空霓虹风格直接套进任意 tsParticles 项目，并能解释它底层每一处颜色的来源。

一、这个调色板定义了什么

cosmic-radiation（展示名 “Cosmic Radiation”）是 tsParticles 官方的一个颜色调色板包，位于 monorepo 的 palettes/space/cosmicRadiation 目录下。官方 README 的定位很明确：调色板只定义颜色，不定义完整行为，必须与一个运行时基础包（如@tsparticles/basic）以及粒子选项搭配使用。

调色板由四部分组成，全部落在 src/options.ts 的IPalette数据对象中：

IPalette的字段契约在引擎接口 engine/src/Core/Interfaces/IPalette.ts 中定义：background: string、blendMode: GlobalCompositeOperation、colors: SingleOrMultiple<IPaletteColors>、name: string。其中每个颜色集合可单独携带fill（含enable、opacity、value）和stroke（含value、width范围）两类配置。

1.1 三组颜色集合的精确数据

README 的 “Colors” 表格只列出了 7 个填充色与背景色，而源码中的数据比表格更丰富——实际上定义了3 组IPaletteColors：

1. 纯填充组：fill.enable = true，7 个颜色值#FF4444、#4444FF、44FF44、#FFFF44、#FF44FF、#44FFFF、#FFFFFF（红、蓝、绿、黄、品红、青、白的高饱和霓虹色）；
2. 细描边组：仅stroke，颜色#FF8888、#8888FF、#88FF88，线宽范围min: 0.7, max: 1.6——对应示例图中那些纤细的彩色圆圈；
3. 填充 + 粗描边组：填充色同上 7 色，描边色#FFFF88、#FF88FF、#88FFFF、#FFFFFF，线宽范围min: 1.8, max: 3.4——对应示例图中“实心圆外加一圈光晕边”的粒子。

随机抽取这三组颜色集合，正是示例截图里“实心圆、空心细圈、带厚边的亮圆”三种形态并存的原因。

注意一处文档与源码的差异：README 概览表格标注 “Fill: false”，但 options.ts 中第 1、3 组颜色的fill.enable均为true，且示例图明显存在大量实心圆。以源码数据为准：该调色板实际是“填充为主、描边为辅”的组合。

二、快速使用清单（继承自原文档）

原文档给出的 Quick checklist 三步流程如下：

1. 安装@tsparticles/engine（或使用下面的 CDN bundle）；
2. 加载一个基础包（例如@tsparticles/basic），并在tsParticles.load(...)之前调用loadCosmicRadiationPalette；
3. 在 options 中应用palette加一份最小粒子配置。

其中第 2 步的“加载顺序”是硬性要求：palette字符串是在引擎启动实例时才去PluginManager的palettes表里查名的（见下文第三节），如果loadCosmicRadiationPalette(engine)还没执行，查名会静默失败，颜色配置不会生效。

三、CDN / Vanilla JS / jQuery 用法

原文档给出的 CDN 引入方式为（script标签按顺序加载基础包与调色板包）：

<script src="https://cdn.jsdelivr.net/npm/@tsparticles/basic@4/tsparticles.basic.bundle.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/@tsparticles/palette-cosmicRadiation@4/tsparticles.palette-coloredSmokeAmber.min.js"></script>

脚本加载后即可按原文档示例初始化：

(async engine => { await loadBasic(engine); await loadCosmicRadiationPalette(engine); const options = { particles: { number: { value: 200 }, shape: { type: "circle" }, size: { value: { min: 10, max: 15 } }, move: { enable: true, speed: 2, }, }, palette: "cosmicRadiation", }; await engine.load({ id: "tsparticles", options, }); })(tsParticles);

这里有两个基于源码核对后需要留意的细节：

• 调色板注册名。index.ts 中paletteName的实际取值是"cosmic-radiation"（连字符写法），注册逻辑为engine.pluginManager.register(e => e.pluginManager.addPalette(paletteName, options))。因此按源码事实，options 中应写palette: "cosmic-radiation"才能命中注册表；README 示例中的cosmicRadiation与该注册名不一致，使用时请以源码注册名为准做相应调整。
• CDN 包名。package.json 声明的 npm 包名是@tsparticles/palette-cosmic-radiation（连字符写法），版本4.3.3；而 README 徽标与 CDN 路径沿用了@tsparticles/palette-cosmicRadiation甚至tsparticles.palette-coloredSmokeAmber.min.js之类的旧文件名，明显是从其他调色板 README 复制而来。拉取 CDN 时建议以package.json中的实际包名为准核对产物文件名。

CDN 之所以能全局暴露loadCosmicRadiationPalette，是因为 browser.ts 会把函数挂到globalThis.loadCosmicRadiationPalette上；package.json的exports字段也为浏览器环境专门指定了./dist/browser/index.js入口。

四、npm / 模块化用法

package.json 提供了标准与 lazy 双入口，exports映射如下（节选）：

• .：types/browser/import/require/umd分别指向dist/types、dist/browser、dist/esm、dist/cjs、dist/umd下的index.js；
• ./lazy：同样五种条件，指向index.lazy.js——该入口来自 index.lazy.ts，区别在于register回调内部对./options.js做动态import()，让调色板数据真正延迟加载，适合按需加载场景；
• 包还声明了"sideEffects": false，对打包器摇树优化友好。

因此模块化项目的典型写法是：

import { tsParticles, loadBasic } from "@tsparticles/basic"; import { loadCosmicRadiationPalette } from "@tsparticles/palette-cosmic-radiation"; // 或按需延迟：from "@tsparticles/palette-cosmic-radiation/lazy" await loadBasic(tsParticles.engine); await loadCosmicRadiationPalette(tsParticles.engine); await tsParticles.load({ id: "tsparticles", options: { particles: { number: { value: 200 }, shape: { type: "circle" }, size: { value: { min: 10, max: 15 } }, move: { enable: true, speed: 2 }, }, palette: "cosmic-radiation", }, });

对 React、Vue、Angular、Svelte、jQuery、Preact 等组件库用户，原文档的建议是：查阅对应组件库仓库的文档，同样调用loadCosmicRadiationPalette(engine)。本仓库的 wrappers/ 目录收录了这些框架的封装包源码，可作为调用方式的参照。

五、引擎如何消费 palette：从字符串到画布颜色

这是理解“为什么调色板不需要你手写颜色”的关键，全部可以在引擎源码中找到依据。

1. 注册阶段：PluginManager.addPalette实现于 engine/src/Core/Utils/PluginManager.ts，逻辑极简——this.palettes.set(name, palette)，把名称映射到IPalette对象存入内部表。

2. 顶层解析阶段：当engine.load()的 options 里出现palette字段时，Options.ts 的构造函数会执行this.palette = data.palette并调用私有方法#importPalette(palette)（Options.ts#L142-L161）。该方法通过pluginManager.getPalette(palette)取回调色板数据，若查不到则直接return（这也是“必须先 load 调色板”的原因），否则自动合并三项配置：

this.load({ background: { color: paletteData.background }, // #020204 blend: { enable: true, mode: paletteData.blendMode }, // screen particles: { palette }, // 把调色板名透传给粒子层 });

也就是说，你只写一行palette: "cosmic-radiation"，背景色与screen混合模式就由引擎替你填好了。

3. 粒子层应用阶段：ParticlesOptions.ts 的doLoad在检测到data.palette时同样调用自身的#importPalette，把调色板绑定到粒子的 paint（填充/描边）配置上；粒子渲染时再从调色板的colors集合中随机抽取填充色与描边色。从源码结构看，这正是示例图中三种圆形形态的生成机制：每组颜色集合被视作一个候选样式，逐粒子随机命中。

六、自定义与覆盖

原文档的 Customization 部分特别强调：和任何标准 tsParticles 安装一样，所有 options 都可以按常规方式覆盖。结合第五节的解析顺序（#importPalette使用this.load({...})合并配置），意味着：

• 先由调色板写入background/blend/ 粒子颜色；
• 你在同一份 options 中显式写的background、blend、particles等属性仍可覆盖这些默认值，比如把blend.mode改成lighter、把size.value调小以营造“辐射尘埃”的细密感；
• 若要彻底脱离调色板颜色，直接配置particles下的fill/stroke而不设palette即可。

七、小结与仓库内延伸阅读

• 调色板数据本体：src/options.ts（7 填充色、两套描边、背景#020204、screen混合）；
• 注册与延迟加载：src/index.ts、src/index.lazy.ts；
• CDN 全局挂载：src/browser.ts；
• 数据契约：engine/src/Core/Interfaces/IPalette.ts；
• 消费管线：engine/src/Core/Utils/PluginManager.ts、engine/src/Options/Classes/Options.ts、engine/src/Options/Classes/Particles/ParticlesOptions.ts；
• 原始文档：README，效果截图：sample.png。

掌握“调色板 = 数据 + 名称注册，引擎负责解析合并”这一模型后，你可以用完全相同的方式使用仓库palettes/目录下的其他调色板（如 palettes/fire、palettes/food 下的系列），或参照本目录结构自建调色板包。

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