tsParticles AutumnLeaves 秋叶调色板：安装配置、色彩定义与引擎级实现原理

tsParticles AutumnLeaves 秋叶调色板：安装配置、色彩定义与引擎级实现原理

【免费下载链接】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 的 Autumn Leaves 调色板（@tsparticles/palette-autumn-leaves）为粒子效果提供一套以秋叶为主题的暖色配色：从深红、橙黄到落叶棕共 8 种填充色，并配以深色背景与source-over混合模式。本文以 palettes/nature/autumnLeaves/README.md 为骨架，结合其源码与引擎实现，完整讲解该调色板的色彩构成、安装方式、配置写法，以及"调色板如何被 tsParticles 引擎解析并应用到粒子与背景"的底层原理，读完即可在你的页面中直接复现秋叶飘落效果。

调色板是什么：只定义颜色，不定义行为

tsParticles 的调色板（Palette）与预设（Preset）是两种不同机制：预设会一次性注入一整套包含形状、数量、运动等行为的完整配置，而调色板只负责颜色。AutumnLeaves 官方文档明确提示：

A palette defines colors, not complete behavior, so pair it with a runtime package and particle options.

也就是说，使用 AutumnLeaves 时你需要自己决定粒子用什么形状、多少数量、如何运动，调色板只保证"颜色是秋天的那套"。因此推荐搭配@tsparticles/basic（提供基础形状与运动能力）这类运行时包一起使用，再用少量 particles 配置描述行为即可。

色彩构成一览

AutumnLeaves 调色板的全部颜色定义在 palettes/nature/autumnLeaves/src/options.ts 中，与 README 中的色表完全一致：

对应的options.ts源码如下，其中colors.fill以数组形式承载 8 个色值，enable: true表示启用填充色：

export const options: IPalette = { name: "Autumn Leaves", background: "#1a0e04", blendMode: "source-over", colors: { fill: { enable: true, value: [ "#CC2200", "#EE4400", "#FF6600", "#FF9900", "#FFCC00", "#AAAA00", "#886633", "#553311", ], }, }, };

从引擎的调色板接口 engine/src/Core/Interfaces/IPalette.ts 可以看到，一个调色板由name、background（背景色）、blendMode（画布全局混合模式）和colors（填充色/描边色，支持opacity透明度区间与width描边宽度等扩展项）四部分构成。colors.value使用SingleOrMultiple<string>类型，意味着既可以是单个色值，也可以是像这里一样的多色数组，引擎会从中随机取色。

安装方式：npm 与 CDN

该调色板作为独立包发布，npm 包名为@tsparticles/palette-autumn-leaves（见 palettes/nature/autumnLeaves/package.json），版本与引擎同步。安装时你需要同时准备引擎/基础包：

npm install @tsparticles/engine @tsparticles/basic @tsparticles/palette-autumn-leaves

如果不想使用包管理器，可以通过 jsDelivr 直接加载 CDN 构建产物：

<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-autumn-leaves@4/tsparticles.palette-autumn-leaves.min.js"></script>

注意：README 与package.dist.json中的jsdelivr/unpkg字段仍保留着旧项目遗留的文件名tsparticles.palette-coloredSmokeAmber.min.js，实际包名与构建产物应为@tsparticles/palette-autumn-leaves（文件名tsparticles.palette-autumn-leaves.min.js）。使用 CDN 时请以上述修正后的 URL 为准，或直接改用 npm 安装方式避免歧义。

包内按exports提供了主入口（dist/esm/index.js）与./lazy懒加载入口（dist/esm/index.lazy.js），并同时输出 browser、CJS、UMD 等格式，可在 package.dist.json 中查看完整映射。

快速开始：最小可用配置

加载脚本后，按以下顺序调用即可：先加载基础运行时包，再加载调色板插件，最后通过palette选项引用它：

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

这是一个"调色板 + 最小行为配置"的典型组合：200 个圆形粒子、大小 10～15 随机、以速度 2 缓慢飘动，颜色则完全交给 AutumnLeaves 调色板。

关键调用顺序：loadBasic(engine)与loadAutumnLeavesPalette(engine)都必须在engine.load(...)之前await完成。调色板通过 palettes/nature/autumnLeaves/src/index.ts 中的loadAutumnLeavesPalette注册为引擎插件：

const paletteName = "autumn-leaves"; export async function loadAutumnLeavesPalette(engine: Engine): Promise<void> { await engine.pluginManager.register(e => { e.pluginManager.addPalette(paletteName, options); }); }

自定义：覆盖任意标准 tsParticles 选项

官方文档强调：调色板的所有定义都可以像普通 tsParticles 配置一样被覆盖。例如你可以在 options 中显式设置background、blend或particles.color，从而在保留秋叶色感的同时调整背景或粒子外观：

const options = { background: { color: "#000000", // 覆盖调色板默认背景 #1a0e04 }, blend: { enable: true, mode: "source-over", }, particles: { number: { value: 120 }, shape: { type: "circle" }, size: { value: { min: 5, max: 20 } }, move: { enable: true, speed: 3, direction: "bottom" }, // 改为向下飘落，更接近落叶 color: { value: ["#CC2200", "#EE4400", "#FF9900", "#886633"], // 手动指定秋叶色子集 }, opacity: { value: 0.8 }, }, };

direction: "bottom"结合随机起始位置即可模拟"树叶飘落"；若想要更真实的落叶轨迹，还可叠加 paths 路径插件（如 paths/zigzag）或 updaters 中的 wobble（见 updaters/wobble）让粒子左右摇摆。

在框架组件中使用

对于 React、Vue（2.x/3.x）、Angular、Svelte、jQuery、Preact、Solid 等框架，tsParticles 提供了对应的组件库（见 wrappers 目录）。在组件库场景下，只需在初始化引擎后调用loadAutumnLeavesPalette(engine)，其余逻辑与原生用法一致：

import { tsParticles } from "@tsparticles/engine"; import { loadBasic } from "@tsparticles/basic"; import { loadAutumnLeavesPalette } from "@tsparticles/palette-autumn-leaves"; await loadBasic(tsParticles); await loadAutumnLeavesPalette(tsParticles);

之后在组件配置中设置palette: "autumn-leaves"（或直接沿用上面示例中的 particles 行为配置）即可。框架组件包的初始化入口与用法细节可参考对应 wrapper 的 README，例如 wrappers/react、wrappers/vue3。

源码原理：从注册到生效的完整链路

注册的调色板名是autumn-leaves

一个容易被忽略的细节：options.ts中调色板的显示名是"Autumn Leaves"，而index.ts中注册到引擎的键名（paletteName）是 kebab-case 的"autumn-leaves"。因此配置项应写为palette: "autumn-leaves"才能命中引擎查找，README 示例中的"autumnLeaves"是历史遗留写法。引擎通过 PluginManager 的addPalette(name, palette)与getPalette(name)完成注册与按名查找。

引擎如何把调色板应用到画布

当配置中出现palette字段时，引擎在 engine/src/Options/Classes/Options.ts 中调用私有方法#importPalette完成三件事：

#importPalette(palette: string): void { const paletteData = this.#pluginManager.getPalette(palette); if (!paletteData) { return; // 未注册的调色板名会被静默忽略 } this.load({ background: { color: paletteData.background }, // 1. 注入背景色 blend: { enable: true, mode: paletteData.blendMode }, // 2. 启用混合模式 particles: { palette }, // 3. 把调色板键名传给粒子 }); }

也就是说，palette: "autumn-leaves"最终会被展开为：背景色#1a0e04、画布混合模式source-over、粒子颜色引用该调色板。如果传入的调色板名未被注册，getPalette返回undefined，导入会被静默跳过——这也是"先loadAutumnLeavesPalette(engine)再engine.load(...)"这一顺序如此重要的原因。

懒加载与浏览器全局暴露

除了常规入口，该包还提供懒加载变体 palettes/nature/autumnLeaves/src/index.lazy.ts：通过import("@tsparticles/engine/lazy")延迟引入引擎，并把options改为异步import("./options.js")，适合希望进一步压缩首屏体积的按需加载场景。浏览器入口 palettes/nature/autumnLeaves/src/browser.ts 则把loadAutumnLeavesPalette挂到globalThis上，这就是 CDN 方式下全局函数可直接调用的原因。

使用要点小结

• 调色板只定义颜色，行为需自行配置，推荐与@tsparticles/basic等运行时包搭配；
• 注册键名为autumn-leaves，配置中应写palette: "autumn-leaves"；
• 必须先await loadBasic(engine)与loadAutumnLeavesPalette(engine)，再调用engine.load(...)；
• 所有调色板定义（背景、混合模式、颜色）均可被常规 options 覆盖；
• 该包同时提供标准入口、懒加载入口与浏览器全局入口，npm 与 CDN 两种使用方式皆可，CDN 文件名以tsparticles.palette-autumn-leaves.min.js为准。

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