tsParticles Cog 齿轮形状深度指南配置参数、源码原理与版本演进全解析【免费下载链接】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/shape-cog包的 CHANGELOG.md 为主线结合该包在 tsParticles 仓库中的 README.md 与完整 TypeScript 源码系统讲解 Cog齿轮形状粒子的安装方式、配置参数、绘制原理与版本演进脉络。读完本篇你将掌握如何在 tsParticles 中启用 cog 形状、精确控制齿轮的齿数、内外径与锥度并从源码层面理解齿轮路径是如何逐点生成的。一、Cog 形状包是什么tsParticles 的形状shape决定了每个粒子的外观轮廓。官方内置了circle、square、star等常见形状而齿轮形状以独立包tsparticles/shape-cog的形式发布包描述为 tsParticles shape for rendering particles as cog or gear shapes即专门用于将粒子渲染为齿轮 / 棘轮形状的扩展详见 shapes/cog/package.json。从 CHANGELOG 可以看到Cog 形状是在v2.10.02023-06-03版本中作为新功能被加入的对应提交信息 added new cog shapeCHANGELOG.md 中 v2.10.0 条目。此后该包随 tsParticles 主仓库一同演进当前版本为 4.3.3。该包与引擎的关系非常纯粹tsparticles/engine是唯一的 peerDependency它只负责向引擎注册一个名为cog的形状绘制器不包含任何动画或交互逻辑。二、安装与快速上手1. CDN / Vanilla JS / jQuery在 CDN 场景下只需引入tsparticles.shape.cog.min.js文件它会向全局暴露loadCogShape函数该行为由 shapes/cog/src/browser.ts 实现将loadCogShape挂载到globalThis。加载脚本后即可初始化(async () { await loadCogShape(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* options */ /* 这里可以使用 particles.shape.type: cog */ }, }); })();2. ESM / CommonJS该包同时兼容 ES Module 与 CommonJS 两种模块规范安装方式$ npm install tsparticles/shape-cog或使用 yarn$ yarn add tsparticles/shape-cogCommonJS 方式const { tsParticles } require(tsparticles/engine); const { loadCogShape } require(tsparticles/shape-cog); (async () { await loadCogShape(tsParticles); })();ESM 方式import { tsParticles } from tsparticles/engine; import { loadCogShape } from tsparticles/shape-cog; (async () { await loadCogShape(tsParticles); })();package.json中的exports字段为不同模块环境提供了types/browser/import/require四条入口并额外提供./lazy子路径用于按需懒加载对应 shapes/cog/src/index.lazy.ts配合sideEffects: false声明可被打包器安全地进行 tree-shaking。三、配置参数详解1. 选项映射主选项键particles.shape.type: cog形状专属选项键particles.shape.options.cog最小可用配置如下{ particles: { shape: { type: cog, options: { cog: {} } } } }options.cog为空对象时所有齿轮参数均使用默认值。2. 可调参数与默认值齿轮形状的完整参数由 shapes/cog/src/ICogData.ts 中的ICogData接口定义五个参数全部为可选且类型均为RangeValue即既可以填一个固定数值也可以填{ min, max }区间让引擎在区间内随机取值参数默认值含义holeRadius44中心孔半径占粒子半径的百分比innerRadius72齿根内圈半径占粒子半径的百分比innerTaper35齿根锥度控制齿谷收窄程度notches7齿数outerTaper50齿顶锥度控制齿峰收窄程度完整配置示例带注释{ particles: { shape: { type: cog, options: { cog: { holeRadius: 44, innerRadius: 72, innerTaper: 35, notches: 7, outerTaper: 50 } } } } }3. 参数在粒子初始化时的处理上述默认值定义在 shapes/cog/src/CogDrawer.ts 顶部const defaultHoleRadius 44, defaultInnerRadius 72, defaultInnerTaper 35, defaultNotches 7, defaultOuterTaper 50;在particleInit中每个粒子创建时会通过getRangeValue从配置读取这些值CogDrawer.tsparticleInit(_container: Container, particle: CogParticle): void { const shapeData particle.shapeData; particle.cogHoleRadius getRangeValue(shapeData?.holeRadius ?? defaultHoleRadius); particle.cogInnerRadius getRangeValue(shapeData?.innerRadius ?? defaultInnerRadius); particle.cogInnerTaper getRangeValue(shapeData?.innerTaper ?? defaultInnerTaper); particle.cogNotches getRangeValue(shapeData?.notches ?? defaultNotches); particle.cogOuterTaper getRangeValue(shapeData?.outerTaper ?? defaultOuterTaper); }getRangeValue是引擎提供的工具函数如果配置值是数字则原样返回如果是{ min, max }对象则在区间内随机取一个值。因此你可以通过notches: { min: 5, max: 12 }让每个粒子拥有不同的齿数从而形成更自然的粒子效果。这些属性被挂载到CogParticle类型上见 shapes/cog/src/CogParticle.ts供绘制阶段使用。四、源码原理齿轮是如何被绘制出来的1. 绘制器结构与默认生命周期CogDrawer实现了引擎的IShapeDrawer接口包含三个生命周期方法CogDrawer.tsdraw(data)调用drawCog绘制齿轮主体afterDraw(data)调用drawCogHole在主体绘制完成后打孔particleInit初始化每个粒子的齿轮专属属性。draw与afterDraw分离的设计是有意为之先画出完整齿轮再在绘制阶段之后用destination-out合成模式把中心圆孔挖掉这样孔洞不会与后续绘制互相干扰。2. 齿轮轮廓的逐点生成算法核心绘制逻辑位于 shapes/cog/src/Utils.ts 的drawCog函数。首先基于粒子半径与百分比参数换算实际像素值const angle doublePI / (particle.cogNotches * double), taperAI angle * particle.cogInnerTaper * taperFactor, taperAO angle * particle.cogOuterTaper * taperFactor, innerRadius (radius * particle.cogInnerRadius) / percentDenominator;其中percentDenominator为 100即参数按百分比解释double为 2taperFactor为 0.005。因此每个齿对应角度为2π / (notches * 2)即每对齿峰 齿谷占一个基本角齿顶锥度角taperAO与齿根锥度角taperAI由百分比参数线性换算控制齿的倾斜程度。随后用一个toggle布尔值在外圈 → 内圈 → 外圈之间交替连线在圆周上逐点生成多边形路径for (; a doublePI; a angle) { if (toggle) { context.lineTo(innerRadius * Math.cos(a - taperAI), innerRadius * Math.sin(a - taperAI)); context.lineTo(radius * Math.cos(a taperAO), radius * Math.sin(a taperAO)); } else { context.lineTo(radius * Math.cos(a - taperAO), radius * Math.sin(a - taperAO)); context.lineTo(innerRadius * Math.cos(a taperAI), innerRadius * Math.sin(a taperAI)); } toggle !toggle; }可以理解为起点落在外圈某处随后交替折回内圈齿谷 → 回到外圈齿峰如此往复绕满一整圈 2π最终形成一个锯齿状的封闭齿轮轮廓。3. 中心孔洞的挖除drawCogHole使用 Canvas 的destination-out全局合成模式先画一个半径为radius * cogHoleRadius / 100的实心圆再切回source-overcontext.globalCompositeOperation destination-out; context.beginPath(); context.moveTo(holeRadius, originPoint.y); context.arc(originPoint.x, originPoint.y, holeRadius, minAngle, doublePI); context.closePath(); context.fill(); context.globalCompositeOperation source-over;destination-out会删除目标区域已有的像素从而在齿轮中心挖出一个透明圆孔——这正是afterDraw独立存在的意义。如果该函数提前返回例如某些粒子属性尚未初始化齿轮将表现为实心无孔。4. 形状注册机制入口函数loadCogShape(engine)在 shapes/cog/src/index.ts 中实现export async function loadCogShape(engine: Engine): Promisevoid { engine.checkVersion(__VERSION__); await engine.pluginManager.register(e { e.pluginManager.addShape([cog], () Promise.resolve(new CogDrawer())); }); }它先调用engine.checkVersion(__VERSION__)校验引擎版本兼容性再通过pluginManager.register将cog名称与CogDrawer实例关联。懒加载版本index.lazy.ts则用动态import(./CogDrawer.js)将绘制器代码拆分为独立 chunk进一步缩小初始包体积。五、从 CHANGELOG 看版本演进CHANGELOG 记录了两个层面的变更包自身的功能变更与跟随主仓库的引擎级变更。大多数条目标注为 Version bump only for package tsparticles/shape-cog表示该版本只是随 monorepo 整体发版包代码本身没有改动——理解这一点有助于正确解读日志。1. 包的关键功能里程碑v2.10.02023-06-03Features 中包含 added new cog shape这是 Cog 形状的诞生版本同期还加入了 arrow箭头形状与基于 SVG 路径的 path 插件v2.11.0随引擎支持 tree shaking 与插件加载的 refresh flag配合本包sideEffects: false与./lazy导出让按需打包成为可能v3.0.0-beta.1正确支持 npmexports选项即 package.json 中现在的多入口导出结构v3.4.0引擎改为不再预加载插件的 bundle 加载方式插件的加载时机变得更加可控v4.0.0-alpha.4移除部分重复常量并新增 manual particles 插件v4.0.0 之后进入 4.x 稳定周期当前 4.3.3 为最新版本。2. 值得注意的 Bug 修复CHANGELOG 中的修复大多发生在引擎层但直接关系 Cog 形状的渲染稳定性例如v3.8.1修复 fullScreen 激活时的 z-index 样式问题issue #5458——当粒子背景全屏显示时层级错乱会影响所有形状的显示v3.7.1修复 canvas 尺寸变化resize问题——窗口缩放时齿轮形状需跟随重绘v3.6.0修复颜色语法问题issue #5409齿轮作为形状同样受益于颜色解析的修复v3.6.0-beta.0修复 out modes粒子移出边界模式问题v3.3.0修复 Chrome 中异步requestAnimationFrame导致的问题并减少 async 方法以适配 Vite 构建v3.2.2修复循环依赖检测与动态导入相关问题——这与index.lazy.ts的懒加载机制直接相关v3.0.3修复 emoji 内存管理问题在元素带 id 时优先使用 id。可以看出Cog 形状包本身很小其稳定性高度依赖tsparticles/engine的持续演进这也是它保持唯一 peerDependency 是引擎这一设计的原因。六、常见陷阱与最佳实践结合 README 的 Common pitfalls 与源码实现实践中需要注意加载顺序必须在tsParticles.load(...)之前await loadCogShape(tsParticles)。因为load会立即根据配置解析形状类型若此时cog尚未注册会报形状未找到之类的错误。参数按百分比解释holeRadius、innerRadius是粒子半径的百分比除以 100不是绝对像素。若把 44 误当作 44px齿轮会走形。齿数不宜过小notches决定齿数过小的值会让齿轮退化为三角形等奇怪轮廓同时齿数在doublePI / (notches * 2)中被用作除数必须为正数。渐进式调试一次只调整一组参数先只改notches再改锥度便于快速定位回归原因这也是 README 推荐的排障方式。类型化配置TypeScript 项目中可引入ICogData类型约束options.cog的写法避免拼写错误。七、继续深入阅读包使用文档shapes/cog/README.md绘制器与默认参数shapes/cog/src/CogDrawer.ts齿轮轮廓 / 中心孔绘制算法shapes/cog/src/Utils.ts配置接口定义shapes/cog/src/ICogData.ts粒子扩展类型shapes/cog/src/CogParticle.ts形状注册入口含懒加载变体shapes/cog/src/index.ts、shapes/cog/src/index.lazy.ts包元信息与多模块导出shapes/cog/package.json完整版本历史shapes/cog/CHANGELOG.md如果你正在为网站背景、彩纸confetti或烟花效果寻找一种机械感、齿轮感的粒子造型tsparticles/shape-cog是最直接的方案安装、注册、配置三步即可而理解其绘制源码后你还可以通过RangeValue随机化参数让每个齿轮粒子都独一无二。【免费下载链接】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），仅供参考
