tsParticles Cog Shape 使用指南用齿轮粒子为网页动画注入机械质感【免费下载链接】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为讲解主体完整介绍如何在 tsParticles 中引入并配置 cog齿轮形状粒子覆盖 CDN、ESM、CommonJS 三种加载方式、形状专属选项的完整参数说明并结合仓库源码解析齿轮绘制算法的实现原理与常见坑点。读完本文你将能在自己的项目中独立接入齿轮粒子并学会通过holeRadius、innerRadius、notches等参数精确控制齿轮外观。Cog Shape 是什么tsparticles/shape-cog是 tsParticles 生态中的附加形状插件additional cog shape它让粒子不再局限于圆形、方形等基础几何体而是以机械齿轮cog / gear的外形在画布上旋转、运动。该项目位于仓库的 shapes/cog 目录其package.json中的描述为 tsParticles shape for rendering particles as cog or gear shapes明确点出了该形状的用途。keywords字段中同时收录了cog与gear方便开发者在 npm 上检索。从包结构看该插件体积小巧核心代码只有 5 个 TypeScript 源文件CogDrawer.ts绘制器、CogParticle.ts粒子类型扩展、ICogData.ts形状配置数据结构、Utils.ts齿轮绘制算法、index.ts/index.lazy.ts加载入口。整体遵循 tsParticles 形状插件实现IShapeDrawer接口 提供loadXxx加载函数的标准范式。快速接入清单按照官方 README 的 Quick checklist接入 cog 形状只需三步安装tsparticles/engine或直接使用下方 CDN bundle在调用tsParticles.load(...)之前先调用本包的加载函数loadCogShape(...)在tsParticles.load(...)的配置中将particles.shape.type设置为cog。需要特别强调的是第 2 步的时序加载函数必须先于load执行否则引擎在解析配置时找不到名为cog的绘制器粒子将无法按预期渲染详见下文常见坑点。如何安装与使用CDN / Vanilla JS / jQuery 方式CDN/Vanilla 版本在纯 HTML 场景下只需引入一个核心 JS 文件tsparticles.shape.cog.min.js。引入该文件后全局作用域会暴露一个用于加载形状的函数loadCogShape脚本加载完成后即可初始化tsParticles并启用 cog 形状示例代码如下(async () { await loadCogShape(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* options */ /* here you can use particles.shape.type: cog */ }, }); })();loadCogShape(tsParticles)的调用会向引擎的插件管理器注册 cog 绘制器。从 browser.ts 的源码可以看到浏览器入口会把loadCogShape挂载到globalThis上同时维护__tsParticlesInternals内部命名空间这就是 Vanilla 场景下全局函数可直接调用的原因。ESM / CommonJS 方式该包同时兼容 ES Module 与 CommonJS。首先通过包管理器安装$ npm install tsparticles/shape-cog或$ yarn add tsparticles/shape-cog然后按模块规范导入。CommonJS 写法const { tsParticles } require(tsparticles/engine); const { loadCogShape } require(tsparticles/shape-cog); (async () { await loadCogShape(tsParticles); })();ES Module 写法import { tsParticles } from tsparticles/engine; import { loadCogShape } from tsparticles/shape-cog; (async () { await loadCogShape(tsParticles); })();从 package.json 的exports字段可以看出该包为不同运行环境提供了多份产物dist/esm/index.jsimport、dist/cjs/index.jsrequire、dist/browser/index.js浏览器并声明tsparticles/engine为 peerDependency仓库内版本为workspace:*因此使用前必须先保证引擎依赖就绪。懒加载入口lazy import除了默认入口该包还提供tsparticles/shape-cog/lazy子路径对应 index.lazy.ts。懒加载版本在注册插件时通过动态import(./CogDrawer.js)按需加载绘制器代码适合希望进一步压缩首屏 bundle 体积的场景。两种入口都调用engine.checkVersion(__VERSION__)做版本一致性校验避免引擎与插件版本不匹配。选项映射与完整配置选项键位Cog 形状在 tsParticles 配置中的映射关系如下主选项键particles.shape.type: cog形状专属选项键particles.shape.options.cog最小可用配置{ particles: { shape: { type: cog, options: { cog: {} } } } }options.cog可以为空对象此时引擎会为所有齿轮参数套用默认值依旧能渲染出完整的齿轮粒子。完整参数说明options.cog支持的全部参数定义在 ICogData.ts 中每个字段的类型都是RangeValue既可以是固定数值也可以是{ min, max }区间对象引擎会通过getRangeValue在区间内随机取值所有字段均为可选参数类型默认值含义holeRadiusRangeValue44齿轮中心圆孔半径以粒子半径的百分比计innerRadiusRangeValue72齿轮齿根内圈半径以粒子半径的百分比计innerTaperRangeValue35齿根处锥度数值越大齿根切角越明显notchesRangeValue7齿轮齿数凹槽/轮齿数量outerTaperRangeValue50齿顶处锥度数值越大齿顶切角越明显以上默认值来自 CogDrawer.ts 中定义的常量defaultHoleRadius 44、defaultInnerRadius 72、defaultInnerTaper 35、defaultNotches 7、defaultOuterTaper 50并通过particleInit方法在粒子初始化时写入粒子实例。一个更完整的、带参数的配置示例{ particles: { shape: { type: cog, options: { cog: { holeRadius: 30, innerRadius: 80, innerTaper: 25, notches: 9, outerTaper: 45 } } }, move: { enable: true, speed: 2 } } }参数如何作用到粒子实例从 CogDrawer.ts 的particleInit实现可以看到配置值会在粒子初始化时被解析并绑定到粒子实例上形成 CogParticle.ts 中定义的扩展属性cogHoleRadius、cogInnerRadius、cogInnerTaper、cogNotches、cogOuterTaper。每个属性都经过getRangeValue处理因此即使传入{ min, max }区间每个粒子也会获得略有差异的外观让整个粒子群体更富自然感。源码解析齿轮是如何被绘制出来的Cog 形状的绘制逻辑集中在 Utils.tsCogDrawer将其拆分为两个阶段draw绘制齿轮主体drawCog函数使用 Canvas 2D 的moveTo/lineTo多边形路径算法生成齿轮轮廓。核心计算如下每齿对应的角度步长angle 2π / (notches * 2)即每个轮齿由两段夹角组成内外锥度角taperAI angle * innerTaper * 0.005、taperAO angle * outerTaper * 0.005其中taperFactor 0.005是缩放系数把百分比化的 taper 值换算成实际弧度内圈半径innerRadius radius * cogInnerRadius / 100引擎常量percentDenominator 100见 Constants.ts与holeRadius同理都是百分比换算。随后通过toggle标志在外圈齿顶 — 内圈齿根之间交替连线绕满 2π 即完成闭合的齿轮多边形。outerTaper控制齿顶的切角宽度innerTaper控制齿根处的内切深度两者共同决定了齿轮齿形的锋利或圆润程度。afterDraw抠出中心圆孔drawCogHole在齿轮主体绘制完成之后执行对应IShapeDrawer接口的afterDraw生命周期。其关键在于设置context.globalCompositeOperation destination-out绘制一个以holeRadius为半径的圆用目标擦除合成模式把中心区域挖空形成齿轮的通孔效果之后再恢复为source-over。这也是CogDrawer同时实现draw与afterDraw两个方法的原因。注册机制loadCogShape 内部通过engine.pluginManager.addShape([cog], () Promise.resolve(new CogDrawer()))将cog形状名映射到CogDrawer实例。因此配置中shape.type: cog正是与该注册名一一对应。如果你想扩展多个名称addShape接受名称数组这意味着从源码结构看该插件后续可以低成本地为同一绘制器注册别名。常见坑点与排查建议README 中明确列出了三个常见问题结合源码可进一步解释其成因在loadCogShape(...)之前调用tsParticles.load(...)这是最典型的错误。若load先执行引擎解析shape.type: cog时绘制器尚未注册齿轮无法渲染。务必保证await loadCogShape(tsParticles)先完成。启用高级选项前先确认 peer 依赖tsparticles/shape-cog依赖tsparticles/enginepeerDependency且部分视觉效果可能还涉及其他插件如旋转依赖 rotate 相关能力。如果选项不生效先检查引擎版本是否与插件兼容checkVersion会在不匹配时给出提示再检查相关插件是否已加载。一次只修改一个选项组齿轮形状有 5 个互相影响的参数齿数、内外半径、内外锥度同时改动多个值容易引入难定位的回归。建议逐个选项组调整、单独刷新验证快速隔离问题来源。相关资源全部包目录与更多形状插件请参考仓库根目录 README.md引擎核心与完整 API 文档位于engine目录形状绘制接口IShapeDrawer定义在 engine/src/Core本包完整源码见 shapes/cog/src配置文件见 shapes/cog/package.json其余形状插件如circle、square、star、text等位于 shapes 目录接入方式与 cog 完全一致可对照参考掌握上述接入流程与参数语义后你可以把齿轮粒子用作网页的机械风动态背景、加载动画或交互点缀配合 tsParticles 的旋转、颜色、透明度等通用能力快速产出视觉独特的粒子效果。【免费下载链接】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），仅供参考 tsParticles Cog Shape 使用指南：用齿轮粒子为网页动画注入机械质感
tsParticles Cog Shape 使用指南用齿轮粒子为网页动画注入机械质感【免费下载链接】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为讲解主体完整介绍如何在 tsParticles 中引入并配置 cog齿轮形状粒子覆盖 CDN、ESM、CommonJS 三种加载方式、形状专属选项的完整参数说明并结合仓库源码解析齿轮绘制算法的实现原理与常见坑点。读完本文你将能在自己的项目中独立接入齿轮粒子并学会通过holeRadius、innerRadius、notches等参数精确控制齿轮外观。Cog Shape 是什么tsparticles/shape-cog是 tsParticles 生态中的附加形状插件additional cog shape它让粒子不再局限于圆形、方形等基础几何体而是以机械齿轮cog / gear的外形在画布上旋转、运动。该项目位于仓库的 shapes/cog 目录其package.json中的描述为 tsParticles shape for rendering particles as cog or gear shapes明确点出了该形状的用途。keywords字段中同时收录了cog与gear方便开发者在 npm 上检索。从包结构看该插件体积小巧核心代码只有 5 个 TypeScript 源文件CogDrawer.ts绘制器、CogParticle.ts粒子类型扩展、ICogData.ts形状配置数据结构、Utils.ts齿轮绘制算法、index.ts/index.lazy.ts加载入口。整体遵循 tsParticles 形状插件实现IShapeDrawer接口 提供loadXxx加载函数的标准范式。快速接入清单按照官方 README 的 Quick checklist接入 cog 形状只需三步安装tsparticles/engine或直接使用下方 CDN bundle在调用tsParticles.load(...)之前先调用本包的加载函数loadCogShape(...)在tsParticles.load(...)的配置中将particles.shape.type设置为cog。需要特别强调的是第 2 步的时序加载函数必须先于load执行否则引擎在解析配置时找不到名为cog的绘制器粒子将无法按预期渲染详见下文常见坑点。如何安装与使用CDN / Vanilla JS / jQuery 方式CDN/Vanilla 版本在纯 HTML 场景下只需引入一个核心 JS 文件tsparticles.shape.cog.min.js。引入该文件后全局作用域会暴露一个用于加载形状的函数loadCogShape脚本加载完成后即可初始化tsParticles并启用 cog 形状示例代码如下(async () { await loadCogShape(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* options */ /* here you can use particles.shape.type: cog */ }, }); })();loadCogShape(tsParticles)的调用会向引擎的插件管理器注册 cog 绘制器。从 browser.ts 的源码可以看到浏览器入口会把loadCogShape挂载到globalThis上同时维护__tsParticlesInternals内部命名空间这就是 Vanilla 场景下全局函数可直接调用的原因。ESM / CommonJS 方式该包同时兼容 ES Module 与 CommonJS。首先通过包管理器安装$ npm install tsparticles/shape-cog或$ yarn add tsparticles/shape-cog然后按模块规范导入。CommonJS 写法const { tsParticles } require(tsparticles/engine); const { loadCogShape } require(tsparticles/shape-cog); (async () { await loadCogShape(tsParticles); })();ES Module 写法import { tsParticles } from tsparticles/engine; import { loadCogShape } from tsparticles/shape-cog; (async () { await loadCogShape(tsParticles); })();从 package.json 的exports字段可以看出该包为不同运行环境提供了多份产物dist/esm/index.jsimport、dist/cjs/index.jsrequire、dist/browser/index.js浏览器并声明tsparticles/engine为 peerDependency仓库内版本为workspace:*因此使用前必须先保证引擎依赖就绪。懒加载入口lazy import除了默认入口该包还提供tsparticles/shape-cog/lazy子路径对应 index.lazy.ts。懒加载版本在注册插件时通过动态import(./CogDrawer.js)按需加载绘制器代码适合希望进一步压缩首屏 bundle 体积的场景。两种入口都调用engine.checkVersion(__VERSION__)做版本一致性校验避免引擎与插件版本不匹配。选项映射与完整配置选项键位Cog 形状在 tsParticles 配置中的映射关系如下主选项键particles.shape.type: cog形状专属选项键particles.shape.options.cog最小可用配置{ particles: { shape: { type: cog, options: { cog: {} } } } }options.cog可以为空对象此时引擎会为所有齿轮参数套用默认值依旧能渲染出完整的齿轮粒子。完整参数说明options.cog支持的全部参数定义在 ICogData.ts 中每个字段的类型都是RangeValue既可以是固定数值也可以是{ min, max }区间对象引擎会通过getRangeValue在区间内随机取值所有字段均为可选参数类型默认值含义holeRadiusRangeValue44齿轮中心圆孔半径以粒子半径的百分比计innerRadiusRangeValue72齿轮齿根内圈半径以粒子半径的百分比计innerTaperRangeValue35齿根处锥度数值越大齿根切角越明显notchesRangeValue7齿轮齿数凹槽/轮齿数量outerTaperRangeValue50齿顶处锥度数值越大齿顶切角越明显以上默认值来自 CogDrawer.ts 中定义的常量defaultHoleRadius 44、defaultInnerRadius 72、defaultInnerTaper 35、defaultNotches 7、defaultOuterTaper 50并通过particleInit方法在粒子初始化时写入粒子实例。一个更完整的、带参数的配置示例{ particles: { shape: { type: cog, options: { cog: { holeRadius: 30, innerRadius: 80, innerTaper: 25, notches: 9, outerTaper: 45 } } }, move: { enable: true, speed: 2 } } }参数如何作用到粒子实例从 CogDrawer.ts 的particleInit实现可以看到配置值会在粒子初始化时被解析并绑定到粒子实例上形成 CogParticle.ts 中定义的扩展属性cogHoleRadius、cogInnerRadius、cogInnerTaper、cogNotches、cogOuterTaper。每个属性都经过getRangeValue处理因此即使传入{ min, max }区间每个粒子也会获得略有差异的外观让整个粒子群体更富自然感。源码解析齿轮是如何被绘制出来的Cog 形状的绘制逻辑集中在 Utils.tsCogDrawer将其拆分为两个阶段draw绘制齿轮主体drawCog函数使用 Canvas 2D 的moveTo/lineTo多边形路径算法生成齿轮轮廓。核心计算如下每齿对应的角度步长angle 2π / (notches * 2)即每个轮齿由两段夹角组成内外锥度角taperAI angle * innerTaper * 0.005、taperAO angle * outerTaper * 0.005其中taperFactor 0.005是缩放系数把百分比化的 taper 值换算成实际弧度内圈半径innerRadius radius * cogInnerRadius / 100引擎常量percentDenominator 100见 Constants.ts与holeRadius同理都是百分比换算。随后通过toggle标志在外圈齿顶 — 内圈齿根之间交替连线绕满 2π 即完成闭合的齿轮多边形。outerTaper控制齿顶的切角宽度innerTaper控制齿根处的内切深度两者共同决定了齿轮齿形的锋利或圆润程度。afterDraw抠出中心圆孔drawCogHole在齿轮主体绘制完成之后执行对应IShapeDrawer接口的afterDraw生命周期。其关键在于设置context.globalCompositeOperation destination-out绘制一个以holeRadius为半径的圆用目标擦除合成模式把中心区域挖空形成齿轮的通孔效果之后再恢复为source-over。这也是CogDrawer同时实现draw与afterDraw两个方法的原因。注册机制loadCogShape 内部通过engine.pluginManager.addShape([cog], () Promise.resolve(new CogDrawer()))将cog形状名映射到CogDrawer实例。因此配置中shape.type: cog正是与该注册名一一对应。如果你想扩展多个名称addShape接受名称数组这意味着从源码结构看该插件后续可以低成本地为同一绘制器注册别名。常见坑点与排查建议README 中明确列出了三个常见问题结合源码可进一步解释其成因在loadCogShape(...)之前调用tsParticles.load(...)这是最典型的错误。若load先执行引擎解析shape.type: cog时绘制器尚未注册齿轮无法渲染。务必保证await loadCogShape(tsParticles)先完成。启用高级选项前先确认 peer 依赖tsparticles/shape-cog依赖tsparticles/enginepeerDependency且部分视觉效果可能还涉及其他插件如旋转依赖 rotate 相关能力。如果选项不生效先检查引擎版本是否与插件兼容checkVersion会在不匹配时给出提示再检查相关插件是否已加载。一次只修改一个选项组齿轮形状有 5 个互相影响的参数齿数、内外半径、内外锥度同时改动多个值容易引入难定位的回归。建议逐个选项组调整、单独刷新验证快速隔离问题来源。相关资源全部包目录与更多形状插件请参考仓库根目录 README.md引擎核心与完整 API 文档位于engine目录形状绘制接口IShapeDrawer定义在 engine/src/Core本包完整源码见 shapes/cog/src配置文件见 shapes/cog/package.json其余形状插件如circle、square、star、text等位于 shapes 目录接入方式与 cog 完全一致可对照参考掌握上述接入流程与参数语义后你可以把齿轮粒子用作网页的机械风动态背景、加载动画或交互点缀配合 tsParticles 的旋转、颜色、透明度等通用能力快速产出视觉独特的粒子效果。【免费下载链接】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），仅供参考