tsParticles Emitters Shape Circle 插件完全指南从安装配置到圆形发射区算法原理【免费下载链接】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 官方发射器形状插件tsparticles/plugin-emitters-shape-circle仓库路径 plugins/emittersShapes/circle系统讲解它的安装方式、加载顺序、配置入口与底层实现原理。读完本文你将掌握如何在tsParticles.load(...)中配置圆形/椭圆发射区域理解fill、size、shape.type等参数如何影响粒子生成并能从源码层面看懂圆形发射区随机采样拒绝采样式椭圆均匀分布的数学实现直接应用于烟火、喷泉、泡泡等自定义粒子特效场景。插件是什么给 Emitters 增加 circle 发射区形状tsParticles 的 Emitters 插件tsparticles/plugin-emitters允许你在画布中定义发射器——一块持续或按频率产生粒子的区域。发射器的形状决定了粒子从怎样的几何区域中出生默认内置square形状而 plugins/emittersShapes/circle 这个插件则补充了circle圆形/椭圆形发射区。它的本质是一个极小的注册型插件不引入新的顶级配置键而是向 Emitters 的形状管理器注册一个名为circle的 shape generator。注册之后你在emitter.shape.type: circle时即可触发圆形发射逻辑。从源码结构看该插件由 4 个核心文件组成EmittersCircleShape.ts —— 圆形发射区形状类实现随机出生点算法EmittersCircleShapeGenerator.ts —— 形状工厂负责实例化EmittersCircleShapeindex.ts —— 加载入口导出loadEmittersShapeCircle加载函数index.lazy.ts —— 懒加载lazy变体入口按需动态 import。安装与加载必须遵守的先后顺序与所有 tsParticles 插件一样正确使用本插件有严格的三步走安装或通过 CDN 引入tsparticles/engine与tsparticles/plugin-emitters在调用tsParticles.load(...)之前先调用插件的加载函数在tsParticles.load(...)的 options 配置中应用对应参数。CDN / Vanilla JS / jQuery 方式在浏览器中通过 CDN 引入tsparticles.plugin.emitters.shape.circle.min.js文件后全局会暴露loadEmittersShapeCircle函数(async () { await loadEmittersPlugin(tsParticles); await loadEmittersShapeCirclePlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: {/* options */}, }); })();注意原文档给出的函数名为loadEmittersShapeCirclePlugin在当前仓库源码中browser.ts 实际导出的全局函数为loadEmittersShapeCircleindex.ts 中导出的加载函数名二者所指相同以当前源码导出名为准。ESM / CommonJS 方式先安装包package 名来自 package.json 的name字段$ npm install tsparticles/plugin-emitters-shape-circle或使用 yarn$ yarn add tsparticles/plugin-emitters-shape-circleCommonJS 引入方式const { tsParticles } require(tsparticles/engine); const { loadEmittersPlugin } require(tsparticles/plugin-emitters); const { loadEmittersShapeCirclePlugin } require(tsparticles/plugin-emitters-shape-circle); (async () { await loadEmittersPlugin(tsParticles); await loadEmittersShapeCirclePlugin(tsParticles); })();ESM 引入方式import { tsParticles } from tsparticles/engine; import { loadEmittersPlugin } from tsparticles/plugin-emitters; import { loadEmittersShapeCirclePlugin } from tsparticles/plugin-emitters-shape-circle; (async () { await loadEmittersPlugin(tsParticles); await loadEmittersShapeCirclePlugin(tsParticles); })();无论哪种模块方式加载顺序都不可颠倒必须先加载tsparticles/plugin-emitters再加载本形状插件。原因在源码中一目了然——index.ts 的注册回调里调用了ensureEmittersPluginLoaded(e)而该函数见 ensureEmittersPluginLoaded.ts会在 emitters 插件未加载时直接抛出错误tsParticles Emitters Plugin is not loaded。此外engine.checkVersion(__VERSION__)还会校验引擎与插件的版本兼容性。懒加载Lazy入口如果你关心首屏包体可以使用tsparticles/plugin-emitters-shape-circle/lazy子路径见 package.json 的 exports 配置。对应的 index.lazy.ts 会通过await import(...)动态加载tsparticles/plugin-emitters/lazy与形状生成器把插件代码拆成独立 chunk仅在运行时需要时才拉取。配置入口emitter.shape.type: circle本插件不引入独立的顶层 options 键而是直接挂载在 Emitters 插件的既有配置结构之下。完整的发射器配置形如await tsParticles.load({ id: tsparticles, options: { emitters: { position: { x: 50, y: 50 }, // 发射器中心位置百分比 size: { width: 40, height: 30, mode: percent }, // 发射区宽高 fill: true, // 粒子出生在区域内false 则只从边缘出生 shape: { type: circle, // 关键使用圆形发射区 options: {}, // 圆形状暂无额外选项 replace: { color: false, opacity: false }, }, rate: { quantity: 1, delay: 0.1 }, }, }, });关键配置项的语义与来源配置项类型默认值说明源码依据emitter.shape.typestringsquare发射区形状类型插件注册后可使用circleEmitterShape.tsemitter.shape.optionsRecordstring, unknown{}形状专属选项圆形状无需额外参数EmitterShape.tsemitter.shape.replace{color, opacity}false/false是否用形状填充色/透明度覆盖出生粒子的颜色/透明度EmitterShapeReplace.tsemitter.fillbooleantruetrue时粒子在整个圆/椭圆内部出生false时只在圆周/椭圆周出生Emitter.tsemitter.size{width, height, mode}0/0/percent发射区宽高mode支持percent相对画布百分比或precise像素EmitterSize.tsemitter.position{x, y}—发射器中心坐标与 size 的 mode 对应Emitter.ts关于shape.options从 EmitterShape.ts 的load实现可以看到options会通过deepExtend深合并进 shape 配置而本插件的EmittersCircleShape构造函数接收options后并未使用它见 EmittersCircleShape.ts因此圆形发射区目前没有专属形状参数。size的mode字段需要注意EmitterSize.ts 中默认是PixelMode.percent即宽高按画布百分比计算。width与height的比值决定了发射区是正圆还是椭圆两者相等为正圆不等则为椭圆。底层原理圆形发射区的随机出生点是如何计算的当配置了shape.type: circle后EmitterInstance.ts 会通过emitterShapeManager.getShapeGenerator(shapeOptions.type)找到已注册的 circle generator并调用其generate(...)创建形状实例每次发射粒子时再调用this.#shape.randomPosition()获取随机出生点见 EmitterInstance.ts。EmittersCircleShapeGenerator.generate()EmittersCircleShapeGenerator.ts的作用很单纯把 container、position、size、fill、options 原样传入构造EmittersCircleShape实例。真正的算法核心在 EmittersCircleShape.ts 的randomPosition()中它解决了一个关键问题在椭圆内部均匀随机取点。如果直接用随机角度 随机半径的极坐标方式会在椭圆中心聚集过多粒子密度不均匀。该实现的做法是取半轴长[a, b] [size.width * half, size.height * half]即椭圆的两个半轴均匀生成角度 θgenerateTheta(x, y)使用u getRandom() * quarterquarter即 1/4对应 90°通过theta Math.atan((y / x) * Math.tan(doublePI * u))计算第一象限角度再依据随机变量v的四个区间把 θ 映射到四个象限θ、π−θ、πθ、−θ从而在[0, 2π)上均匀分布。这里利用了椭圆上角度均匀分布 ⇔ 对应辅助圆参数角均匀分布的数学性质计算该角度下的椭圆半径radius(x, y, θ) (x·y) / sqrt((y·cos θ)² (x·sin θ)²)即椭圆在角度 θ 方向上的边界半径squareExp即指数 2按 fill 决定径向距离randomRadius fill ? maxRadius * Math.sqrt(getRandom()) : maxRadius。当fill: true时半径乘以sqrt(getRandom())——由于面积正比于 r²对 r² 均匀采样等价于对面积均匀采样从而保证粒子在圆/椭圆内部面积均匀分布中心不会堆积当fill: false时randomRadius恒等于maxRadius所有粒子只落在圆周/椭圆周上。最终出生点坐标为position randomRadius * (cos θ, sin θ)叠加到发射器中心位置之上。EmittersCircleShape继承自 EmitterShapeBasetsparticles/plugin-emitters提供的抽象基类基类负责统一管理position、size、fill、options四个字段并提供resize()供容器尺寸变化时同步更新发射区子类只需实现init()此处为空实现见 EmittersCircleShape.ts和randomPosition()。常见坑位排查原文档给出了三条实战提醒结合源码可进一步展开在tsParticles.load(...)之前必须完成插件加载。因为EmitterInstance创建时会立即用shape.type查询形状生成器EmitterInstance.ts若circle尚未注册查询结果为undefined#shape不会创建后续randomPosition()也不会执行——发射器会退化为使用this.position单点发射见 EmitterInstance.ts表现上就是没有圆形区域效果。确认 peer 依赖已就绪。本插件的 package.json 声明tsparticles/engine与tsparticles/plugin-emitters为 peerDependencies缺失或版本不匹配会触发ensureEmittersPluginLoaded的报错或checkVersion的版本校验失败。一次只改动一个配置组。fill、size.mode、shape.type、rate相互独立又共同影响粒子出生表现逐项调整便于快速定位回归原因。扩展阅读形状注册与查询的基础设施ShapeManager.ts内部用Mapstring, IEmitterShapeGenerator管理全部形状生成器、addEmittersShapesManager.ts向 engine 挂载addEmitterShapeGenerator方法、EmittersEngine.ts扩展后的引擎类型发射器完整配置项Emitter.ts、IEmitter.ts形状选项加载逻辑EmitterShape.ts 与 EmitterShapeReplace.ts其他发射器形状实现可参考仓库plugins/emittersShapes/目录下的其他子包结构与本插件一致。【免费下载链接】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），仅供参考