尧图网站建设 
tsParticles Canvas Mask 插件深度指南基于 CHANGELOG 的功能演进、配置解析与像素级实现原理【免费下载链接】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/tsparticlestsParticles 的 Canvas Mask画布遮罩插件能够将图片、文本乃至外部 canvas 元素的像素信息转化为粒子群让粒子特效绘制出任意图形或文字。本文以插件 CHANGELOG.md 记录的功能演进为主线结合插件源码与配置文件完整讲解该插件的安装加载方式、全部配置项、文本/图片/画布三种遮罩输入源以及从像素到粒子的底层实现原理帮助你快速上手并在自己的页面中复现 Logo 粒子、文字粒子等视觉效果。一、插件定位与功能演进概览Canvas Mask 是 tsParticles 官方维护的插件包名为tsparticles/plugin-canvas-maskv2 时代为tsparticles-plugin-canvas-mask。从 CHANGELOG 可以梳理出这条清晰的功能演进线2.3.02022-09-11插件首个版本一次性落地了四个核心能力——支持文本与通用 canvas 输入、字体font选项、位置position选项、以及使用外部创建的 canvas 元素element 选项对应提交 [0770c13] 与 [c576656] 等。2.4.02022-10-30为文本遮罩加入多行文本支持并修复了多行文本下遮罩尺寸输出错误的问题对应提交 [eceacbe]、[9b00acc]。2.7.02022-12-23粒子添加顺序改为基于getRandom的随机打乱shuffle让遮罩粒子呈现更自然的分布提交 [0161280]。2.10.02023-06-03大版本聚合更新包含标准化错误前缀、为引擎加入版本号、移除所有 canvas context 的 save/restore 调用性能优化、新增 motion 插件配合、新增 SVG 路径 path 插件等提交 [208722f] 等。3.x 系列2023-2025进入动态导入与加载机制优化阶段——3.2.0 起插件仅在使用时加载dynamic imports3.4.0 改变 bundle 加载方式不再预加载插件3.7.0 引入命名颜色插件与引擎 hex 颜色3.8.1 修复全屏模式下 z-index 样式问题。4.0.0-alpha.272026-03-09一个重要的 API 变更——用particles.fill取代particles.color使粒子填充与描边particles.stroke拥有几乎一致的选项结构提交 [d1793cc]。这意味着在 v4 配置中粒子颜色相关的遮罩覆盖配置需要写在paint.fill之下见下文实现原理。4.0.22026-05-16修复 peer dependencies 问题4.2.02026-06-17修复 eslint 配置与循环依赖。当前仓库中该插件的最新版本为4.3.32026-07-23见 package.json主版本号 4.x 对应 tsParticles 引擎 v4 系列。二、安装与加载三步接入指南插件的使用遵循先加载插件、再加载实例的固定顺序这一点在 README.md 的 Quick checklist 中被明确强调安装tsparticles/engine或直接引入 CDN bundle在调用tsParticles.load(...)之前先调用插件的加载函数在tsParticles.load(...)的配置中启用canvasMask选项。2.1 CDN / Vanilla JS 方式引入tsparticles.plugin.canvas-mask.min.js后全局会暴露loadCanvasMaskPlugin函数用法如下(async () { await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: {/* options */}, }); })();2.2 ESM / CommonJS 方式$ npm install tsparticles/plugin-canvas-mask # 或 $ yarn add tsparticles/plugin-canvas-maskimport { tsParticles } from tsparticles/engine; import { loadCanvasMaskPlugin } from tsparticles/plugin-canvas-mask; (async () { await loadCanvasMaskPlugin(tsParticles); })();CommonJS 用户使用require同样可以const { tsParticles } require(tsparticles/engine); const { loadCanvasMaskPlugin } require(tsparticles/plugin-canvas-mask); (async () { await loadCanvasMaskPlugin(tsParticles); })();从 package.json 可以看出该包通过exports字段同时提供了 ESM、CJS、浏览器与类型声明四种入口并额外暴露了./lazy子路径对应 index.lazy.ts支持按需懒加载。插件对tsparticles/engine声明了 peer dependency因此引擎与插件版本需要配套使用——这正是 CHANGELOG 4.0.2 fixed peer dependencies 修复的核心背景。2.3 加载的底层机制loadCanvasMaskPlugin注册的是一个实现IPlugin接口的类见 CanvasMaskPlugin.tsexport class CanvasMaskPlugin implements IPlugin { readonly id canvas-mask; async getPlugin(container: Container): PromiseIContainerPlugin { const { CanvasMaskPluginInstance } await import(./CanvasMaskPluginInstance.js); return new CanvasMaskPluginInstance(container); } needsPlugin(options?: RecursivePartialICanvasMaskOptions): boolean { return options?.canvasMask?.enable ?? false; } }三个关键点与 CHANGELOG 中的修复项一一对应按需创建实例getPlugin使用动态import加载CanvasMaskPluginInstance这正是 3.2.0 plugins will be loaded only if used仅在使用时加载的落地方式启用开关needsPlugin只检查options.canvasMask.enable只有配置了canvasMask.enable: true时插件才会真正生效懒加载能力import()的动态引入方式配合sideEffects: false见 package.json让打包工具可以安全地对插件进行 tree-shaking。三、三种遮罩输入源图片、文本与外部 canvasCanvas Mask 的核心能力是读取像素、生成粒子。插件支持三种输入源这一能力源自 2.3.0 的 added support to text and generic canvas input 与 added element options ... for using an external created canvas并在 CanvasMaskPluginInstance.ts 的init()方法中按优先级分支处理async init(): Promisevoid { const container this.#container, options container.actualOptions.canvasMask; if (!options?.enable) { return; } let pixelData: CanvasPixelData { pixels: [], height: 0, width: 0 }; const offset options.pixels.offset; if (options.image) { const url options.image.src; if (!url) return; pixelData await getImageData(url, offset, container.canvas.render.settings); } else if (options.text) { const data getTextData(textOptions, offset, textOptions.fill, container.canvas.render.settings); if (isNull(data)) return; pixelData data; } else if (options.element ?? options.selector) { const canvas options.element ?? (options.selector safeDocument().querySelectorHTMLCanvasElement(options.selector)); if (!canvas) return; const context canvas.getContext(2d, container.canvas.render.settings); if (!context) return; pixelData getCanvasImageData(context, canvas, offset); } addParticlesFromCanvasPixels(container, pixelData, options.position, options.scale, options.override, options.pixels.filter); }三种输入源的优先级为图片 文本 外部 canvas 元素/选择器配置了多个时只会采用最先匹配的那个。3.1 图片遮罩image通过image.src指定图片地址支持任意可通过Image加载的 URL包括 data URI 与跨域资源——后者需要服务端配合 CORS。像素提取由tsparticles/canvas-utils中的getImageData完成其核心思想是将图片绘制到离屏 canvas 上再按pixels.offset的采样步长读取RGBA像素数据。const options { canvasMask: { enable: true, image: { src: /images/your-logo.png, // 任意可加载的图片地址 }, pixels: { offset: 4 }, // 采样步长越大粒子越稀疏 scale: 1, position: { x: 50, y: 50 }, }, };3.2 文本遮罩text文本遮罩是插件最常用的场景制作文字粒子标语。2.3.0 加入字体选项、2.4.0 加入多行文本支持最终形成了text下的三层结构const options { canvasMask: { enable: true, text: { text: Hello\nWorld, // 支持 \n 换行2.4.0 多行文本 color: #000000, // 遮罩采样颜色默认黑色 fill: true, // true填充模式false描边模式 font: { // 2.3.0 加入的字体选项 family: sans-serif, // 字体族默认 sans-serif size: 100, // 字号默认 100 style: , // 如 italic variant: , // 如 small-caps weight: , // 如 bold }, lines: {}, // 多行文本的行间距等控制 }, }, };对应源码 TextMask.ts 中默认值为color #000000、fill true、text FontTextMask.ts 中family sans-serif、size 100其余四项默认空字符串。多行文本由 TextMaskLine.ts 类承载getTextData在渲染文本时会根据行配置测量每一行的宽高因此 2.4.0 专门修复了多行文本下遮罩尺寸输出的问题提交 [9b00acc]。提示fill: true会按文字填充区域采样适合大字标语fill: false则只采样文字笔画轮廓可做出空心粒子字效果。3.3 外部 canvas 元素/选择器element / selector这是 2.3.0 element options ... for using an external created canvas 与 2.10.0 generic canvas input 所扩展的能力直接把页面中已有的canvas元素作为粒子来源适合把任意绘制结果图表、签名、绘画作品转化为粒子。// 方式一直接传入 canvas 元素仅限运行时 JS 配置 const myCanvas document.querySelector(#my-canvas); const options { canvasMask: { enable: true, element: myCanvas, // HTMLCanvasElement 实例 position: { x: 50, y: 50 }, }, }; // 方式二通过 CSS 选择器适用于 JSON 配置 const options { canvasMask: { enable: true, selector: #my-canvas, }, };注意 CanvasMask.ts 的load()方法对element做了严格校验只有data.element instanceof HTMLCanvasElement才会被接受因此element选项无法通过纯 JSON 配置传递JSON 中无法承载 DOM 对象JSON 配置请使用selector。这一选择器 vs 元素的双通道设计在init()中合并处理options.element ?? (options.selector safeDocument().querySelector(options.selector))。四、核心配置项全解析顶层canvasMask配置对象由 CanvasMask.ts 定义除三种输入源外还包含以下关键项配置项类型默认值说明enablebooleanfalse总开关needsPlugin仅凭此项决定插件是否加载position{ x, y }{ x: 50, y: 50 }遮罩在画布中的位置百分比值2.3.0 加入提交 [8759b84]scalenumber1遮罩缩放系数放大可让粒子间距成倍拉开overrideobject见下是否用像素颜色/透明度覆盖粒子外观pixelsobject见下像素采样与过滤控制element/selector-无外部 canvas 输入源见 3.34.1 position百分比定位position的取值是 0~100 的百分比见 utils.ts 中percentDenominator参与计算x: 50, y: 50表示遮罩居中。换算公式为const positionOffset { x: (canvasSize.width * position.x) / percentDenominator - width * scale * half, y: (canvasSize.height * position.y) / percentDenominator - height * scale * half, };即画布宽高 × 百分比减去遮罩实际尺寸的一半从而让遮罩以百分比点为中心对齐。4.2 override用像素信息覆盖粒子外观CanvasMaskOverride.ts 提供两个开关配置项默认值说明override.colortrue用像素 RGBA 颜色作为粒子填充色override.opacityfalse用像素 alpha 覆盖粒子透明度在 v4 中颜色覆盖写入了paint.fill对应 4.0.0-alpha.27 的particles.fill取代particles.color变更见 utils.tsif (override.color) { pOptions.paint { fill: { color: { value: pixel }, enable: true, }, }; } if (override.opacity) { pOptions[opacity] { value: pixel.a }; }默认开启颜色覆盖后粒子会直接继承原图的颜色实现像素级还原若关闭override.color粒子则使用粒子配置中的统一颜色。4.3 pixels采样步长与像素过滤CanvasMaskPixels.ts 控制取哪些像素、取多密配置项默认值说明offset4采样步长。每 offset 个像素取一个点值越大粒子越稀疏filter函数像素过滤器默认pixel pixel.a 0只保留非透明像素filter支持两种形式直接传(pixel) boolean函数或传一个已挂载在globalThis上的函数名字符串插件会从全局对象中查找并校验是否为函数。你可以利用它实现只保留指定颜色区域的粒子等高级玩法。五、底层原理从像素矩阵到粒子群addParticlesFromCanvasPixelsutils.ts是整条流水线的终点其算法可以用以下伪代码概括1. 读取像素矩阵 datawidth × height 的 RGBA 二维数组 2. 生成 [0, width*height) 的索引数组并做 Fisher-Yates 洗牌 3. 确定可创建的最大粒子数 min(像素总数, particles.number.value) 4. 循环弹出打乱后的索引 - 将索引还原为 (x, y) 像素坐标 - 用 filter(pixel) 判断该像素是否满足条件 - 满足则按 position/scale 换算屏幕坐标addParticle 生成粒子几个与 CHANGELOG 呼应的实现细节随机打乱2.7.0shuffle()使用引擎的getRandom()而非Math.random()保持随机数来源统一便于调试与复现粒子数量上限maxParticles Math.min(numPixels, container.actualOptions.particles.number.value)——实际粒子数同时受像素总数与particles.number配置约束遮罩越复杂offset 越小粒子越多性能优化2.10.0插件在 v2.10.0 移除了所有 canvas context 的save/restore调用提交 [208722f]减少不必要的上下文状态保存开销3.3.0 又针对 Chrome 修复了异步requestAnimationFrame相关问题减少 vite 构建下的异步方法提交 [2600f6f]。六、常见陷阱与排查建议结合 README.md 的 Common pitfalls 与 CHANGELOG 的修复记录使用中最容易踩的坑如下加载顺序错误在loadCanvasMaskPlugin(tsParticles)之前调用tsParticles.load(...)插件不会生效且不报错。加载函数返回 Promise务必await后再加载实例。enable未开启needsPlugin只认canvasMask.enable忘记开启会导致插件实例不创建、配置被静默忽略。JSON 配置误用elementelement只接受HTMLCanvasElement实例CanvasMask.ts 中有instanceof校验JSON/静态配置必须改用selector。跨域图片无法采样getImageData读取像素受 canvas 同源策略约束跨域图片需服务端返回Access-Control-Allow-Origin并正确配置crossOrigin。版本配套4.0.2 修复了 peer dependencies对应 issue #5763升级插件时需同步升级tsparticles/enginev3 → v4 迁移时注意particles.color已被particles.fill取代。全屏背景的层级问题3.8.1 修复了fullScreen激活时的 z-index 样式问题issue #5458若发现粒子被页面元素遮挡请确认引擎与插件都已升级到包含该修复的版本。七、结语从 CHANGELOG.md 可以完整看到 canvas mask 插件三年的演进轨迹v2 时代奠基了文本/图片/canvas 三种输入源、字体与位置选项、多行文本能力v3 时代转向动态加载、tree-shaking 与加载机制优化v4 时代则跟随引擎完成了particles.fill的选项重构与依赖治理。对于开发者而言理解这段演进史不仅有助于正确配置插件更能帮助你在升级版本时精准定位行为变化。若想深入自定义例如编写自己的像素过滤器或修改采样逻辑可直接阅读 CanvasMaskPluginInstance.ts 与 utils.ts 两处核心源码。【免费下载链接】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 Canvas Mask 插件深度指南：基于 CHANGELOG 的功能演进、配置解析与像素级实现原理
tsParticles Canvas Mask 插件深度指南基于 CHANGELOG 的功能演进、配置解析与像素级实现原理【免费下载链接】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/tsparticlestsParticles 的 Canvas Mask画布遮罩插件能够将图片、文本乃至外部 canvas 元素的像素信息转化为粒子群让粒子特效绘制出任意图形或文字。本文以插件 CHANGELOG.md 记录的功能演进为主线结合插件源码与配置文件完整讲解该插件的安装加载方式、全部配置项、文本/图片/画布三种遮罩输入源以及从像素到粒子的底层实现原理帮助你快速上手并在自己的页面中复现 Logo 粒子、文字粒子等视觉效果。一、插件定位与功能演进概览Canvas Mask 是 tsParticles 官方维护的插件包名为tsparticles/plugin-canvas-maskv2 时代为tsparticles-plugin-canvas-mask。从 CHANGELOG 可以梳理出这条清晰的功能演进线2.3.02022-09-11插件首个版本一次性落地了四个核心能力——支持文本与通用 canvas 输入、字体font选项、位置position选项、以及使用外部创建的 canvas 元素element 选项对应提交 [0770c13] 与 [c576656] 等。2.4.02022-10-30为文本遮罩加入多行文本支持并修复了多行文本下遮罩尺寸输出错误的问题对应提交 [eceacbe]、[9b00acc]。2.7.02022-12-23粒子添加顺序改为基于getRandom的随机打乱shuffle让遮罩粒子呈现更自然的分布提交 [0161280]。2.10.02023-06-03大版本聚合更新包含标准化错误前缀、为引擎加入版本号、移除所有 canvas context 的 save/restore 调用性能优化、新增 motion 插件配合、新增 SVG 路径 path 插件等提交 [208722f] 等。3.x 系列2023-2025进入动态导入与加载机制优化阶段——3.2.0 起插件仅在使用时加载dynamic imports3.4.0 改变 bundle 加载方式不再预加载插件3.7.0 引入命名颜色插件与引擎 hex 颜色3.8.1 修复全屏模式下 z-index 样式问题。4.0.0-alpha.272026-03-09一个重要的 API 变更——用particles.fill取代particles.color使粒子填充与描边particles.stroke拥有几乎一致的选项结构提交 [d1793cc]。这意味着在 v4 配置中粒子颜色相关的遮罩覆盖配置需要写在paint.fill之下见下文实现原理。4.0.22026-05-16修复 peer dependencies 问题4.2.02026-06-17修复 eslint 配置与循环依赖。当前仓库中该插件的最新版本为4.3.32026-07-23见 package.json主版本号 4.x 对应 tsParticles 引擎 v4 系列。二、安装与加载三步接入指南插件的使用遵循先加载插件、再加载实例的固定顺序这一点在 README.md 的 Quick checklist 中被明确强调安装tsparticles/engine或直接引入 CDN bundle在调用tsParticles.load(...)之前先调用插件的加载函数在tsParticles.load(...)的配置中启用canvasMask选项。2.1 CDN / Vanilla JS 方式引入tsparticles.plugin.canvas-mask.min.js后全局会暴露loadCanvasMaskPlugin函数用法如下(async () { await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: {/* options */}, }); })();2.2 ESM / CommonJS 方式$ npm install tsparticles/plugin-canvas-mask # 或 $ yarn add tsparticles/plugin-canvas-maskimport { tsParticles } from tsparticles/engine; import { loadCanvasMaskPlugin } from tsparticles/plugin-canvas-mask; (async () { await loadCanvasMaskPlugin(tsParticles); })();CommonJS 用户使用require同样可以const { tsParticles } require(tsparticles/engine); const { loadCanvasMaskPlugin } require(tsparticles/plugin-canvas-mask); (async () { await loadCanvasMaskPlugin(tsParticles); })();从 package.json 可以看出该包通过exports字段同时提供了 ESM、CJS、浏览器与类型声明四种入口并额外暴露了./lazy子路径对应 index.lazy.ts支持按需懒加载。插件对tsparticles/engine声明了 peer dependency因此引擎与插件版本需要配套使用——这正是 CHANGELOG 4.0.2 fixed peer dependencies 修复的核心背景。2.3 加载的底层机制loadCanvasMaskPlugin注册的是一个实现IPlugin接口的类见 CanvasMaskPlugin.tsexport class CanvasMaskPlugin implements IPlugin { readonly id canvas-mask; async getPlugin(container: Container): PromiseIContainerPlugin { const { CanvasMaskPluginInstance } await import(./CanvasMaskPluginInstance.js); return new CanvasMaskPluginInstance(container); } needsPlugin(options?: RecursivePartialICanvasMaskOptions): boolean { return options?.canvasMask?.enable ?? false; } }三个关键点与 CHANGELOG 中的修复项一一对应按需创建实例getPlugin使用动态import加载CanvasMaskPluginInstance这正是 3.2.0 plugins will be loaded only if used仅在使用时加载的落地方式启用开关needsPlugin只检查options.canvasMask.enable只有配置了canvasMask.enable: true时插件才会真正生效懒加载能力import()的动态引入方式配合sideEffects: false见 package.json让打包工具可以安全地对插件进行 tree-shaking。三、三种遮罩输入源图片、文本与外部 canvasCanvas Mask 的核心能力是读取像素、生成粒子。插件支持三种输入源这一能力源自 2.3.0 的 added support to text and generic canvas input 与 added element options ... for using an external created canvas并在 CanvasMaskPluginInstance.ts 的init()方法中按优先级分支处理async init(): Promisevoid { const container this.#container, options container.actualOptions.canvasMask; if (!options?.enable) { return; } let pixelData: CanvasPixelData { pixels: [], height: 0, width: 0 }; const offset options.pixels.offset; if (options.image) { const url options.image.src; if (!url) return; pixelData await getImageData(url, offset, container.canvas.render.settings); } else if (options.text) { const data getTextData(textOptions, offset, textOptions.fill, container.canvas.render.settings); if (isNull(data)) return; pixelData data; } else if (options.element ?? options.selector) { const canvas options.element ?? (options.selector safeDocument().querySelectorHTMLCanvasElement(options.selector)); if (!canvas) return; const context canvas.getContext(2d, container.canvas.render.settings); if (!context) return; pixelData getCanvasImageData(context, canvas, offset); } addParticlesFromCanvasPixels(container, pixelData, options.position, options.scale, options.override, options.pixels.filter); }三种输入源的优先级为图片 文本 外部 canvas 元素/选择器配置了多个时只会采用最先匹配的那个。3.1 图片遮罩image通过image.src指定图片地址支持任意可通过Image加载的 URL包括 data URI 与跨域资源——后者需要服务端配合 CORS。像素提取由tsparticles/canvas-utils中的getImageData完成其核心思想是将图片绘制到离屏 canvas 上再按pixels.offset的采样步长读取RGBA像素数据。const options { canvasMask: { enable: true, image: { src: /images/your-logo.png, // 任意可加载的图片地址 }, pixels: { offset: 4 }, // 采样步长越大粒子越稀疏 scale: 1, position: { x: 50, y: 50 }, }, };3.2 文本遮罩text文本遮罩是插件最常用的场景制作文字粒子标语。2.3.0 加入字体选项、2.4.0 加入多行文本支持最终形成了text下的三层结构const options { canvasMask: { enable: true, text: { text: Hello\nWorld, // 支持 \n 换行2.4.0 多行文本 color: #000000, // 遮罩采样颜色默认黑色 fill: true, // true填充模式false描边模式 font: { // 2.3.0 加入的字体选项 family: sans-serif, // 字体族默认 sans-serif size: 100, // 字号默认 100 style: , // 如 italic variant: , // 如 small-caps weight: , // 如 bold }, lines: {}, // 多行文本的行间距等控制 }, }, };对应源码 TextMask.ts 中默认值为color #000000、fill true、text FontTextMask.ts 中family sans-serif、size 100其余四项默认空字符串。多行文本由 TextMaskLine.ts 类承载getTextData在渲染文本时会根据行配置测量每一行的宽高因此 2.4.0 专门修复了多行文本下遮罩尺寸输出的问题提交 [9b00acc]。提示fill: true会按文字填充区域采样适合大字标语fill: false则只采样文字笔画轮廓可做出空心粒子字效果。3.3 外部 canvas 元素/选择器element / selector这是 2.3.0 element options ... for using an external created canvas 与 2.10.0 generic canvas input 所扩展的能力直接把页面中已有的canvas元素作为粒子来源适合把任意绘制结果图表、签名、绘画作品转化为粒子。// 方式一直接传入 canvas 元素仅限运行时 JS 配置 const myCanvas document.querySelector(#my-canvas); const options { canvasMask: { enable: true, element: myCanvas, // HTMLCanvasElement 实例 position: { x: 50, y: 50 }, }, }; // 方式二通过 CSS 选择器适用于 JSON 配置 const options { canvasMask: { enable: true, selector: #my-canvas, }, };注意 CanvasMask.ts 的load()方法对element做了严格校验只有data.element instanceof HTMLCanvasElement才会被接受因此element选项无法通过纯 JSON 配置传递JSON 中无法承载 DOM 对象JSON 配置请使用selector。这一选择器 vs 元素的双通道设计在init()中合并处理options.element ?? (options.selector safeDocument().querySelector(options.selector))。四、核心配置项全解析顶层canvasMask配置对象由 CanvasMask.ts 定义除三种输入源外还包含以下关键项配置项类型默认值说明enablebooleanfalse总开关needsPlugin仅凭此项决定插件是否加载position{ x, y }{ x: 50, y: 50 }遮罩在画布中的位置百分比值2.3.0 加入提交 [8759b84]scalenumber1遮罩缩放系数放大可让粒子间距成倍拉开overrideobject见下是否用像素颜色/透明度覆盖粒子外观pixelsobject见下像素采样与过滤控制element/selector-无外部 canvas 输入源见 3.34.1 position百分比定位position的取值是 0~100 的百分比见 utils.ts 中percentDenominator参与计算x: 50, y: 50表示遮罩居中。换算公式为const positionOffset { x: (canvasSize.width * position.x) / percentDenominator - width * scale * half, y: (canvasSize.height * position.y) / percentDenominator - height * scale * half, };即画布宽高 × 百分比减去遮罩实际尺寸的一半从而让遮罩以百分比点为中心对齐。4.2 override用像素信息覆盖粒子外观CanvasMaskOverride.ts 提供两个开关配置项默认值说明override.colortrue用像素 RGBA 颜色作为粒子填充色override.opacityfalse用像素 alpha 覆盖粒子透明度在 v4 中颜色覆盖写入了paint.fill对应 4.0.0-alpha.27 的particles.fill取代particles.color变更见 utils.tsif (override.color) { pOptions.paint { fill: { color: { value: pixel }, enable: true, }, }; } if (override.opacity) { pOptions[opacity] { value: pixel.a }; }默认开启颜色覆盖后粒子会直接继承原图的颜色实现像素级还原若关闭override.color粒子则使用粒子配置中的统一颜色。4.3 pixels采样步长与像素过滤CanvasMaskPixels.ts 控制取哪些像素、取多密配置项默认值说明offset4采样步长。每 offset 个像素取一个点值越大粒子越稀疏filter函数像素过滤器默认pixel pixel.a 0只保留非透明像素filter支持两种形式直接传(pixel) boolean函数或传一个已挂载在globalThis上的函数名字符串插件会从全局对象中查找并校验是否为函数。你可以利用它实现只保留指定颜色区域的粒子等高级玩法。五、底层原理从像素矩阵到粒子群addParticlesFromCanvasPixelsutils.ts是整条流水线的终点其算法可以用以下伪代码概括1. 读取像素矩阵 datawidth × height 的 RGBA 二维数组 2. 生成 [0, width*height) 的索引数组并做 Fisher-Yates 洗牌 3. 确定可创建的最大粒子数 min(像素总数, particles.number.value) 4. 循环弹出打乱后的索引 - 将索引还原为 (x, y) 像素坐标 - 用 filter(pixel) 判断该像素是否满足条件 - 满足则按 position/scale 换算屏幕坐标addParticle 生成粒子几个与 CHANGELOG 呼应的实现细节随机打乱2.7.0shuffle()使用引擎的getRandom()而非Math.random()保持随机数来源统一便于调试与复现粒子数量上限maxParticles Math.min(numPixels, container.actualOptions.particles.number.value)——实际粒子数同时受像素总数与particles.number配置约束遮罩越复杂offset 越小粒子越多性能优化2.10.0插件在 v2.10.0 移除了所有 canvas context 的save/restore调用提交 [208722f]减少不必要的上下文状态保存开销3.3.0 又针对 Chrome 修复了异步requestAnimationFrame相关问题减少 vite 构建下的异步方法提交 [2600f6f]。六、常见陷阱与排查建议结合 README.md 的 Common pitfalls 与 CHANGELOG 的修复记录使用中最容易踩的坑如下加载顺序错误在loadCanvasMaskPlugin(tsParticles)之前调用tsParticles.load(...)插件不会生效且不报错。加载函数返回 Promise务必await后再加载实例。enable未开启needsPlugin只认canvasMask.enable忘记开启会导致插件实例不创建、配置被静默忽略。JSON 配置误用elementelement只接受HTMLCanvasElement实例CanvasMask.ts 中有instanceof校验JSON/静态配置必须改用selector。跨域图片无法采样getImageData读取像素受 canvas 同源策略约束跨域图片需服务端返回Access-Control-Allow-Origin并正确配置crossOrigin。版本配套4.0.2 修复了 peer dependencies对应 issue #5763升级插件时需同步升级tsparticles/enginev3 → v4 迁移时注意particles.color已被particles.fill取代。全屏背景的层级问题3.8.1 修复了fullScreen激活时的 z-index 样式问题issue #5458若发现粒子被页面元素遮挡请确认引擎与插件都已升级到包含该修复的版本。七、结语从 CHANGELOG.md 可以完整看到 canvas mask 插件三年的演进轨迹v2 时代奠基了文本/图片/canvas 三种输入源、字体与位置选项、多行文本能力v3 时代转向动态加载、tree-shaking 与加载机制优化v4 时代则跟随引擎完成了particles.fill的选项重构与依赖治理。对于开发者而言理解这段演进史不仅有助于正确配置插件更能帮助你在升级版本时精准定位行为变化。若想深入自定义例如编写自己的像素过滤器或修改采样逻辑可直接阅读 CanvasMaskPluginInstance.ts 与 utils.ts 两处核心源码。【免费下载链接】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），仅供参考