tsParticles 粒子描边（Stroke）配置迁移指南：从 particles.stroke 到 particles.paint.stroke

tsParticles 粒子描边（Stroke）配置迁移指南：从 particles.stroke 到 particles.paint.stroke

【免费下载链接】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 中粒子描边（Stroke）配置的官方文档展开，说明描边选项为何从旧路径particles.stroke迁移至particles.paint.stroke，并结合引擎源码（engine/src）深入讲解paint分组下stroke的完整参数、默认值与渲染原理。读完本文，你将掌握在 JSON 配置或tsParticles.load()代码中正确书写粒子描边（宽度、颜色、透明度），并理解其与paint.fill、paint.color的协作关系。

背景：为什么 Stroke 选项被归入paint分组

在 Stroke.md 中明确指出，Stroke 选项已被归档到 Particles Paint 文档中，新的配置路径为particles.paint.stroke。这是 tsParticles 将粒子「填充」与「描边」两类绘制选项统一收拢到paint命名空间的设计调整：

• 旧路径：particles.stroke
• 新路径：particles.paint.stroke

从源码可以印证这一分组意图。IPaint.ts 注释写明paint是“grouping fill and stroke so variants can be selected together”，即让填充与描边可以作为同一套变体（variant）被整体选择；Paint.ts 类则通过懒加载方式持有fill与stroke两个子选项：

loadLazyProperty(this, "fill", data.fill, () => new Fill()); loadLazyProperty(this, "stroke", data.stroke, () => new Stroke());

paint分组结构与颜色回退规则

Paint.md 给出的paint属性表如下：

关键回退规则：paint.color是 fill 和 stroke 的基准颜色。当paint.fill.color或paint.stroke.color未设置时，引擎使用paint.color；一旦两者自身设置了color，则优先于paint.color。

默认值在 ParticlesOptions.ts 中初始化，保持历史行为——粒子默认白色且填充：

this.paint.color = new AnimatableColor(); this.paint.color.value = "#fff"; this.paint.fill = new Fill(); this.paint.fill.enable = true;

即：

• paint.color.value默认"#fff"
• paint.fill.enable默认true

paint.stroke完整参数解析

描边选项对应接口 IStroke.ts，其实现类 Stroke.ts 包含三个字段：

其中width与opacity都经由loadRangeProperty加载（见 Stroke.ts），因此二者既可以写死为单个数字，也可以写成{ min, max }让每个粒子在范围内随机取值——这与 tsParticles 一贯的RangeValue约定一致。color则通过AnimatableColor.create创建，说明描边颜色天然支持value加animation（如enable、speed、sync）的动画配置。

需要注意width的默认值是0，这意味着若不配置描边，粒子不会有可见轮廓；描边只在显式设置width > 0时生效。这一点在渲染端也有印证：RenderManager.ts 中只有当strokeWidth大于最小线宽时才设置strokeStyle，并在绘制阶段对带描边的粒子调用context.stroke()（RenderManager.ts）。

配置示例：从迁移前后到完整用法

迁移前（旧路径，已废弃）

{ "particles": { "stroke": { "width": 2, "color": { "value": "#ffffff" } } } }

迁移后（新路径）

Paint.md 中的官方描边示例：

{ "paint": { "color": { "value": "#14b8a6" }, "stroke": { "width": 2, "color": { "value": "#ffffff" } } } }

进阶：范围宽度、透明度与描边颜色动画

结合IStroke的字段能力，可以写出更丰富的描边配置：

{ "particles": { "paint": { "color": { "value": "#14b8a6" }, "stroke": { "width": { "min": 1, "max": 4 }, "opacity": 0.8, "color": { "value": "#ffffff", "animation": { "enable": true, "speed": 1, "sync": false } } } } } }

在 JS/TS 中通过tsParticles.load()使用同样结构：

await tsParticles.load({ id: "tsparticles", options: { particles: { paint: { color: { value: "#14b8a6" }, stroke: { width: 2, color: { value: "#ffffff" }, }, }, }, }, });

与paint.fill的协作：只描边不填充

描边与填充是互补关系：fill.enable为true时粒子内部被填充，为false时仅保留描边轮廓（见 Fill.md）。若想绘制“空心”粒子，可组合配置：

{ "particles": { "paint": { "color": { "value": "#14b8a6" }, "fill": { "enable": false }, "stroke": { "width": 2, "color": { "value": "#ffffff" } } } } }

渲染端对此的分工清晰：填充色与描边色都来自paint体系，RenderManager.ts 通过 updater 的getColorStyles同时取得fill与stroke样式；粒子绘制时先fill()再按线宽stroke()，二者共用同一套颜色回退逻辑。

相关文档索引

• 描边主文档：Paint.md
• 填充选项：Fill.md
• 颜色模型（IColor、IAnimatableColor、IRangeColor）：Color.md
• 粒子选项根文档：Particles.md
• 选项总览：Options.md

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