tsParticles roll 参数详解：用 Roll Updater 为粒子效果创建伪 3D 翻滚视觉

tsParticles roll 参数详解用 Roll Updater 为粒子效果创建伪 3D 翻滚视觉【免费下载链接】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本文围绕 markdown/Options/Particles/Roll.md 展开讲清 tsParticles 中roll粒子翻滚效果的完整配置项、默认值与实战配置写法并结合 updaters/roll 插件的源码解析翻滚动画背后的角度累计、明暗交替与仿 3D 缩放变换原理读完即可在任意项目中正确启用并调参 roll 效果。什么是 roll 翻滚效果tsParticles 的 Roll 是一个 updater 插件npm 包名tsparticles/updater-roll它为粒子附加一个“翻滚”动画粒子在运动过程中其受光的正面/背面着色持续变化从而呈现出类似彩带、硬币或纸屑在空中翻转的伪 3D 观感。官方文档对其的定义是Adds a rolling effect that changes perceived front/back shading while particles move. 在粒子移动时改变其正面/背面的着色感知产生翻滚效果。典型应用场景是 confetti彩带纸屑类预设当矩形纸屑下落时通过 roll 让它看起来在自转而不是平铺飘动。仓库内置的 party 预设就是如此实现的见 presets/party/src/options.ts。完整属性说明含源码默认值官方文档给出的属性表如下继承自 Roll.mdKeyTypeExampleNotesenablebooleantrue/false启用 roll 效果speednumber/range0/{ min: 1, max: 5 }翻滚速度backColorcolor object背面颜色颜色对象格式参见 Color 文档darken.enablebooleantrue/false启用旋转时的变暗darken.valuenumber5变暗百分比enlighten.enablebooleantrue/false启用旋转时的变亮enlighten.valuenumber5变亮百分比其中backColor的颜色对象格式可继续参考 markdown/Options/Color.md。除了上表结合选项类源码 updaters/roll/src/Options/Classes/Roll.ts还可以确认以下默认值与额外字段配置时可作为兜底依据字段默认值说明enablefalse默认关闭必须显式开启speed25未配置时的翻滚速度基准值modevertical翻滚方向取值为枚举both/horizontal/vertical定义见 updaters/roll/src/RollMode.ts。文档属性表中未列出此字段但源码的IRoll接口 updaters/roll/src/Options/Interfaces/IRoll.ts 中明确包含它darken.enable/darken.valuefalse/0见 updaters/roll/src/Options/Classes/RollLight.tsenlighten.enable/enlighten.valuefalse/0同上另外注意speed与darken.value、enlighten.value的类型均为RangeValue即既支持单值数字也支持{ min, max }区间——区间写法会为每个粒子随机取一个值让群体翻滚节奏更自然。明暗着色逻辑源码印证backColor、darken、enlighten三者在源码中的优先级关系很关键见 updaters/roll/src/Utils.ts 的initParticle函数若配置了backColor则优先为粒子写入背面颜色particle.backColor经rangeColorToHsl转成 HSL否则若darken与enlighten同时启用每个粒子会以 50% 概率随机二选一AlterType.darken或AlterType.enlighten并取对应value的随机范围值若只启用其一则所有粒子都使用该种着色。也就是说backColor是“指定翻到背面时显示的颜色”而darken/enlighten是“在原色基础上压暗/提亮若干百分比”的自动方案二者同时配置时backColor生效。快速上手配置示例官方文档的 Quick example 如下仅展示 roll 片段{ roll: { enable: true, speed: { min: 2, max: 6 }, darken: { enable: true, value: 15 }, enlighten: { enable: false, value: 0 } } }根据插件 README 的 “Option mapping”见 updaters/roll/README.mdroll的完整挂载键为particles.roll因此放入tsParticles.load(...)的完整配置应写成{ particles: { roll: { enable: true, speed: { min: 2, max: 6 }, mode: both, backColor: #ff0000, darken: { enable: true, value: 15 }, enlighten: { enable: false, value: 0 } } } }各字段效果说明speed: { min: 2, max: 6 }每个粒子的翻滚速度在 2~6 之间随机避免整齐划一的机械感mode: both同时进行水平与垂直方向的翻滚见下文原理部分对mode的解释darken.value: 15翻转到背光面时压暗 15%若不需要提亮enlighten保持关闭即可想要更强的“硬币翻转”感可同时开启darken与enlighten粒子将随机交替使用两种着色。安装与加载插件roll 属于独立的 updater 插件包启用前必须先把 updater 注册进引擎再调用tsParticles.load(...)。ESM / CommonJS 安装npm install tsparticles/updater-roll # 或 yarn add tsparticles/updater-rollESM 用法import { tsParticles } from tsparticles/engine; import { loadRollUpdater } from tsparticles/updater-roll; (async () { await loadRollUpdater(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* 包含 particles.roll 的配置 */ }, }); })();CommonJS 用法const { tsParticles } require(tsparticles/engine); const { loadRollUpdater } require(tsparticles/updater-roll); (async () { await loadRollUpdater(tsParticles); })();CDN / 原生 JS引入tsparticles.updater.roll.min.js后即可使用导出的loadRollUpdater函数注册方式与上面一致。官方 README 同时列出了几个常见坑Common pitfalls在loadRollUpdater(...)之前就调用了tsParticles.load(...)导致 roll 配置不生效启用高级选项前先确认相关 peer 依赖包已安装出现回归问题时一次只改一个选项组便于定位。源码解析翻滚效果是如何实现的初始化随机相位 速度换算每个粒子被创建时initParticleupdaters/roll/src/Utils.ts会初始化粒子私有的 roll 数据angle初始角度取getRandom() * doublePI即 0~2π 之间随机。随机相位保证了粒子群不会同步翻转speedgetRangeValue(rollOpt.speed) / maxAngle其中maxAngle 360。从源码结构看配置的 speed 数值被当作“度”来对待除以 360 换算成以弧度计的推进量horizontal/vertical由mode决定——both时两者都为真horizontal或vertical时各自单独为真alter按上文“明暗着色逻辑”写入typedarken/enlighten与value。若roll.enable为 false则只写入禁用状态的空数据后续每帧直接跳过。每帧更新角度累计与回绕updateRoll同文件每帧执行const speed data.speed * delta.factor, max doublePI; data.angle speed; if (data.angle max) { data.angle - max; }角度按speed * delta.factor累加delta.factor是帧率归一因子保证不同刷新率下速度一致超过 2π 后减回形成循环翻滚。为什么看起来是“翻转”变换矩阵中的 cos / sin翻滚的视觉核心在 updaters/roll/src/RollUpdater.ts 的getTransformValuesgetTransformValues(particle: Particle): PartialIParticleTransformValues { const roll particle.roll?.enable particle.roll, rollHorizontal roll roll.horizontal, rollVertical roll roll.vertical; return { a: rollHorizontal ? Math.cos(roll.angle) : undefined, d: rollVertical ? Math.sin(roll.angle) : undefined, }; }返回的a与d是粒子绘制变换矩阵的分量a对应水平方向缩放系数cos(angle)d对应垂直方向缩放系数sin(angle)。由此可以推断其视觉模型——粒子并非真的旋转而是用余弦/正弦函数把某一维度在“完整宽度”与“压扁成线”之间往复缩放模拟薄片绕轴翻转时投影宽度周期性变窄再变宽的效果。这也解释了mode三种取值的含义horizontal只缩放水平维度看起来像绕垂直轴翻转vertical只缩放垂直维度默认值看起来像绕水平轴翻转both两个维度同时受角度驱动翻转感最强适合 confetti 纸屑。此外isEnabled中还有两个生效条件粒子未被销毁!particle.destroyed且处于正常状态!particle.spawning同时要求options.roll.enable为 true——这解释了为什么把 roll 配在 emitter 的particles层可以覆盖主配置实现不同粒子组各滚各的。真实预设参考party 预设的 roll 配置仓库内置 party 预设的主粒子配置presets/party/src/options.ts展示了 roll 在 confetti 场景中的完整调参风格{ roll: { enable: true, mode: both, speed: { min: 40, max: 60 }, darken: { enable: true, value: 30 }, enlighten: { enable: true, value: 30 } } }要点高speed40~60配合mode: both让纸屑快速自转动感更强darken与enlighten同时启用且值相等30%每个粒子随机交替变暗/变亮形成明暗闪烁的翻转质感同一配置中emitter 内部的particles.roll.enable: false显式关闭了该层粒子的 roll说明 roll 配置支持在多层粒子选项中分别覆盖。小结与调参建议最小可用配置只需enable: truespeed其余字段均可依赖默认值mode: vertical、明暗关闭想要背面呈纯色如双色纸屑用backColor想要自然明暗变化用darken/enlighten且backColor优先级更高速度建议用{ min, max }区间制造群体随机性方向上用mode: both翻转感最强单方向翻转用horizontal/vertical启用前务必先loadRollUpdater(tsParticles)再tsParticles.load(...)这是最常见的不生效原因。配置项与行为的完整对应关系可回溯到以下源码文件选项类 updaters/roll/src/Options/Classes/Roll.ts、选项接口 updaters/roll/src/Options/Interfaces/IRoll.ts、初始化与更新逻辑 updaters/roll/src/Utils.ts、更新器主体 updaters/roll/src/RollUpdater.ts以及插件说明 updaters/roll/README.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考