用 Canvas 像素重塑粒子tsParticles Canvas Mask 插件完整指南【免费下载链接】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/tsparticlesoutput文章tsParticles Canvas Mask 插件实战让粒子按 Canvas、图片与文字形状生成output文章tsParticles Canvas Mask 插件实战指南用 Canvas、图片与文字重塑粒子形态tsParticles Canvas Mask 插件tsparticles/plugin-canvas-mask允许开发者把一张 HTML Canvas、一幅图片或一段文字作为遮罩源插件会读取其中的像素数据并让粒子按照这些像素的分布位置生成从而让粒子动画呈现出任意想要的轮廓。本文以 plugins/canvasMask/README.md 为主线结合插件源码、官方配置文档与仓库内置示例完整讲解安装加载、配置项、完整可运行示例与底层实现原理帮助你直接上手用粒子复刻 Logo、文字或任意图形。快速清单Quick checklist官方 README 给出了三步上手路径任何使用方式都遵循这个顺序安装tsparticles/engine或引入下方 CDN bundle在调用tsParticles.load(...)之前调用插件的加载函数loadCanvasMaskPlugin(...)在tsParticles.load(...)的配置对象中应用插件选项根级canvasMask配置块。其中第 2 步至关重要插件的加载函数负责把插件注册到引擎的插件管理器中顺序颠倒会导致canvasMask配置被忽略。安装与加载四种主流集成方式CDN / Vanilla JS / jQuery官方在仓库内的演示页面demo/vanilla/views/index.pug直接通过 CDN 方式引入了插件脚本script src/plugin-canvas-mask/tsparticles.plugin.canvas-mask.min.js/script引入tsparticles.plugin.canvas-mask.min.js后全局会导出插件加载函数loadCanvasMaskPlugin。接下来在业务代码中先加载插件再加载 tsParticles(async () { await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* options其中包含 canvasMask 配置块 */ }, }); })();仓库的 playground 演示demo/vanilla/public/javascripts/playground.js也是采用同样模式先await loadCanvasMaskPlugin(tsParticles)再初始化粒子实例。ESM / CommonJS该包同时兼容 ES Module 与 CommonJS。首先安装依赖$ npm install tsparticles/plugin-canvas-mask或使用 yarn$ yarn add tsparticles/plugin-canvas-maskCommonJS 方式const { tsParticles } require(tsparticles/engine); const { loadCanvasMaskPlugin } require(tsparticles/plugin-canvas-mask); (async () { await loadCanvasMaskPlugin(tsParticles); })();ES Module 方式import { tsParticles } from tsparticles/engine; import { loadCanvasMaskPlugin } from tsparticles/plugin-canvas-mask; (async () { await loadCanvasMaskPlugin(tsParticles); })();从 plugins/canvasMask/package.json 可以看到包同时提供mainCJS、moduleESM、browser与types入口因此三种运行环境都能直接使用其peerDependencies为tsparticles/engine并依赖tsparticles/canvas-utils完成像素数据读取。按需懒加载Lazy如果希望只在需要时才加载插件代码可引入懒加载入口plugins/canvasMask/src/index.lazy.ts。该入口内部通过动态import()按需加载CanvasMaskPlugin实现适合与打包器代码分割配合使用包的exports中已声明./lazy子路径。配置项详解根级 canvasMask 配置块虽然 README 的 Option mapping 一节提示该插件主要扩展运行时行为、可能没有单一根级配置键但从源码结构看plugins/canvasMask/src/types.ts插件确实在根级选项上挂载了一个canvasMask对象ICanvasMaskOptions IOptions { canvasMask?: ICanvasMask }。完整的选项说明可参考官方选项文档 markdown/Options/Plugins/CanvasMask.md。canvasMask顶级属性汇总对应 CanvasMask 类属性类型默认值说明elementHTMLCanvasElement—直接作为遮罩源的 canvas 元素实例赋值时源码会做instanceof HTMLCanvasElement校验enablebooleanfalse是否启用 canvas mask 插件imageIImageMask—图片遮罩选项使用图片作为遮罩源时配置overrideCanvasMaskOverride{color: true, opacity: false}粒子颜色/透明度覆盖选项pixelsCanvasMaskPixels{offset: 4, filter: a 0}像素采样选项position{x: number, y: number}{x: 50, y: 50}遮罩原点位置百分比50/50 即居中scalenumber1遮罩的缩放系数selectorstring—用于定位 canvas 元素的 CSS 选择器textTextMask—文字遮罩选项把文字渲染到 canvas 后作为遮罩注意README 中的 Option mapping 是通用模板文本实际使用中直接在options根级写入canvasMask键即可下方示例均为仓库内可直接运行的官方配置。enable 与三种遮罩源插件在运行时只处理enable true的情况CanvasMaskPluginInstance.init并且遮罩源按以下优先级选取只会使用其中一种image从image.src加载图片text把文字渲染到离屏 canvaselement/selector使用页面中已有的 canvas 元素。image图片遮罩ImageMask 类 只有一个src属性即图片地址支持跨域图片源码getImageData中设置了image.crossOrigin Anonymous。图片加载失败时对应 Promise 会被 reject见 utils/canvasUtils/src/Utils.ts。text文字遮罩TextMask 类 支持属性类型默认值说明textstring要渲染为遮罩的文本内容colorstring#000000文本颜色填充或描边色fillbooleantruetrue用fillText填充false用strokeText描边fontFontTextMask见下字体选项linesTextMaskLine见下多行文本选项fontFontTextMask 类family默认sans-serifsize默认100数字会被拼为100px也支持带单位的字符串另有style、variant、weight三个 CSS 字体描述属性默认空字符串。linesTextMaskLine 类separator默认\n按换行拆分多行spacing默认10行间距像素。文字渲染细节在 utils/canvasUtils/src/Utils.ts先按separator拆分文本用measureText逐行测量宽高再据此创建对应尺寸的离屏 canvas按fill决定fillText/strokeText。pixels像素采样CanvasMaskPixels 类 控制从遮罩源读取像素的方式offset默认4读取像素时的步长。对应 RGBA 每像素 4 个字节值为 4 即逐个像素完整采样增大 offset 会跳过更多字节显著减少采样点数、降低粒子数量与计算开销filter像素过滤函数(pixel: IRgba) boolean决定哪些像素允许生成粒子。默认实现为pixel.a 0即只要像素不透明就生成粒子。也支持传入全局函数名字符串源码会从globalThis中查找并校验是否为函数后使用。position 与 scale遮罩的布局position默认{x: 50, y: 50}表示遮罩中心在粒子画布中的百分比位置50% / 50%即居中scale默认1整体缩放遮罩尺寸放大/缩小粒子云的轮廓。在 utils.ts 中可以看到位置换算公式positionOffset (canvasSize * position) / 100 - maskSize * scale / 2即按百分比定位后再减掉半个遮罩尺寸实现以中心对齐。override粒子外观覆盖CanvasMaskOverride 类 决定粒子是否继承遮罩像素的颜色与透明度color默认true为true时粒子的填充色取遮罩像素的 RGBA 值通过paint.fill.color.value注入opacity默认false为true时粒子的透明度取遮罩像素的 alpha 值。从 utils.ts 的实现看颜色覆盖依赖引擎的paint选项透明度覆盖则写入粒子的opacity选项。若期望像素颜色真实生效需要确认当前使用的 bundle 包含对应的 paint 能力完整 bundle 已内置。可运行的完整示例示例一文字遮罩以下配置取自仓库内置示例 utils/configs/src/t/textMask.ts把 Hello 渲染为粒子形状并关闭颜色覆盖以展示随机颜色粒子await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { smooth: true, interactivity: { events: { onHover: { enable: true, mode: bubble } }, modes: { bubble: { distance: 40, duration: 2, opacity: 8, size: 15 } }, }, particles: { move: { direction: none, distance: 2, enable: true, speed: 1 }, number: { value: 600 }, color: { value: random }, shape: { type: [circle, square, triangle] }, size: { value: { min: 1, max: 3 } }, }, canvasMask: { enable: true, override: { color: false }, scale: 1, pixels: { filter: (pixel) pixel.a 0 }, position: { x: 70, y: 30 }, text: { color: #ff0000, font: { size: 500 }, text: Hello, }, }, background: { color: #0d0d0d }, }, });示例二图片遮罩以下配置取自 utils/configs/src/i/imageMask.ts。注意其filter会先剔除过暗的像素RGB 均小于 30 的像素不生成粒子再把不透明像素作为粒子来源await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { smooth: true, particles: { move: { direction: none, distance: 10, enable: true, speed: 1 }, number: { value: 600 }, shape: { type: [circle, square, triangle] }, size: { value: { min: 3, max: 5 } }, }, canvasMask: { enable: true, scale: 5, pixels: { filter: (pixel) pixel.r 30 pixel.g 30 pixel.b 30 ? false : pixel.a 0, }, image: { src: https://particles.js.org/images/hdr/amongus_cyan.png }, }, background: { color: #0d0d0d }, }, });示例三已有 canvas 元素作为遮罩源官方选项文档 markdown/Options/Plugins/CanvasMask.md 给出的基础 JSON 配置展示了selector的用法——页面中必须存在一个 id 为my-mask-canvas的 canvas{ canvasMask: { enable: true, selector: #my-mask-canvas, position: { x: 50, y: 50 }, scale: 1 } }也可以用element直接传入HTMLCanvasElement实例需要脚本中已持有该元素引用。底层原理像素数据如何变成粒子插件注册与选项装载CanvasMaskPlugin 的needsPlugin判断options?.canvasMask?.enable是否为真只有启用时才通过loadOptions创建CanvasMask选项实例并装载用户配置。getPlugin会动态 import 并返回CanvasMaskPluginInstance实例插件 id 为canvas-mask。像素读取与粒子生成CanvasMaskPluginInstance.init()CanvasMaskPluginInstance.ts按图片 → 文字 → 已有 canvas的顺序读取像素图片getImageData(url, offset, render.settings)把图片绘制到临时 canvas 后读取像素文字getTextData(textOptions, offset, fill, render.settings)渲染文字后读取像素canvas 元素getCanvasImageData(context, canvas, offset)直接读取并默认clearRect清空原 canvas。这三者都返回CanvasPixelData { pixels: IRgba[][], width, height }。随后调用addParticlesFromCanvasPixelsutils.ts完成粒子生成其核心逻辑把全部像素索引随机洗牌Fisher-Yates shuffle保证粒子生成位置分散随机maxParticles Math.min(像素总数, particles.number.value)——粒子数量受全局particles.number.value约束不会超过遮罩像素数逐个弹出随机索引计算像素行列坐标经filter(pixel)过滤后把像素坐标乘以scale并加上positionOffset得到粒子实际位置根据override.color/override.opacity注入粒子外观选项最终调用container.particles.addParticle(pos, pOptions)。依赖与兼容性该插件依赖tsparticles/canvas-utils提供上述三个像素读取函数且以tsparticles/engine为 peer 依赖。加载函数内部会通过engine.checkVersion(__VERSION__)做版本校验因此务必保证插件与引擎版本匹配。常见陷阱Common pitfalls官方 README 明确列出了三类高频问题这里结合源码给出原因先调用tsParticles.load(...)再调用loadCanvasMaskPlugin(...)插件未注册时canvasMask配置不会被解析needsPlugin/loadOptions根本不生效粒子会按普通配置生成。务必保证loadCanvasMaskPlugin在tsParticles.load之前await完成启用高级选项前未确认 peer 依赖例如override.color依赖引擎的 paint 能力、override.opacity依赖 opacity 更新逻辑使用精简 bundleslim时需确认对应能力已内置或另行加载一次改动过多选项组不利于排错建议逐个调整position、scale、pixels.offset、pixels.filter、override等配置组便于快速定位回归原因。另外注意element必须是真的HTMLCanvasElement实例源码有instanceof校验传入字符串会被直接忽略。继续深入完整选项表与官方说明markdown/Options/Plugins/CanvasMask.md插件入口与注册逻辑plugins/canvasMask/src/index.ts、plugins/canvasMask/src/CanvasMaskPlugin.ts像素读取工具实现utils/canvasUtils/src/Utils.ts更多可运行的官方配置示例utils/configs/src/t/textMaskMultiline.ts、utils/configs/src/i/imageMaskRepulse.ts浏览器端加载演示demo/vanilla/views/index.pug、demo/vanilla/public/javascripts/playground.js /output文章【免费下载链接】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），仅供参考 用 Canvas 像素重塑粒子：tsParticles Canvas Mask 插件完整指南
用 Canvas 像素重塑粒子tsParticles Canvas Mask 插件完整指南【免费下载链接】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/tsparticlesoutput文章tsParticles Canvas Mask 插件实战让粒子按 Canvas、图片与文字形状生成output文章tsParticles Canvas Mask 插件实战指南用 Canvas、图片与文字重塑粒子形态tsParticles Canvas Mask 插件tsparticles/plugin-canvas-mask允许开发者把一张 HTML Canvas、一幅图片或一段文字作为遮罩源插件会读取其中的像素数据并让粒子按照这些像素的分布位置生成从而让粒子动画呈现出任意想要的轮廓。本文以 plugins/canvasMask/README.md 为主线结合插件源码、官方配置文档与仓库内置示例完整讲解安装加载、配置项、完整可运行示例与底层实现原理帮助你直接上手用粒子复刻 Logo、文字或任意图形。快速清单Quick checklist官方 README 给出了三步上手路径任何使用方式都遵循这个顺序安装tsparticles/engine或引入下方 CDN bundle在调用tsParticles.load(...)之前调用插件的加载函数loadCanvasMaskPlugin(...)在tsParticles.load(...)的配置对象中应用插件选项根级canvasMask配置块。其中第 2 步至关重要插件的加载函数负责把插件注册到引擎的插件管理器中顺序颠倒会导致canvasMask配置被忽略。安装与加载四种主流集成方式CDN / Vanilla JS / jQuery官方在仓库内的演示页面demo/vanilla/views/index.pug直接通过 CDN 方式引入了插件脚本script src/plugin-canvas-mask/tsparticles.plugin.canvas-mask.min.js/script引入tsparticles.plugin.canvas-mask.min.js后全局会导出插件加载函数loadCanvasMaskPlugin。接下来在业务代码中先加载插件再加载 tsParticles(async () { await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { /* options其中包含 canvasMask 配置块 */ }, }); })();仓库的 playground 演示demo/vanilla/public/javascripts/playground.js也是采用同样模式先await loadCanvasMaskPlugin(tsParticles)再初始化粒子实例。ESM / CommonJS该包同时兼容 ES Module 与 CommonJS。首先安装依赖$ npm install tsparticles/plugin-canvas-mask或使用 yarn$ yarn add tsparticles/plugin-canvas-maskCommonJS 方式const { tsParticles } require(tsparticles/engine); const { loadCanvasMaskPlugin } require(tsparticles/plugin-canvas-mask); (async () { await loadCanvasMaskPlugin(tsParticles); })();ES Module 方式import { tsParticles } from tsparticles/engine; import { loadCanvasMaskPlugin } from tsparticles/plugin-canvas-mask; (async () { await loadCanvasMaskPlugin(tsParticles); })();从 plugins/canvasMask/package.json 可以看到包同时提供mainCJS、moduleESM、browser与types入口因此三种运行环境都能直接使用其peerDependencies为tsparticles/engine并依赖tsparticles/canvas-utils完成像素数据读取。按需懒加载Lazy如果希望只在需要时才加载插件代码可引入懒加载入口plugins/canvasMask/src/index.lazy.ts。该入口内部通过动态import()按需加载CanvasMaskPlugin实现适合与打包器代码分割配合使用包的exports中已声明./lazy子路径。配置项详解根级 canvasMask 配置块虽然 README 的 Option mapping 一节提示该插件主要扩展运行时行为、可能没有单一根级配置键但从源码结构看plugins/canvasMask/src/types.ts插件确实在根级选项上挂载了一个canvasMask对象ICanvasMaskOptions IOptions { canvasMask?: ICanvasMask }。完整的选项说明可参考官方选项文档 markdown/Options/Plugins/CanvasMask.md。canvasMask顶级属性汇总对应 CanvasMask 类属性类型默认值说明elementHTMLCanvasElement—直接作为遮罩源的 canvas 元素实例赋值时源码会做instanceof HTMLCanvasElement校验enablebooleanfalse是否启用 canvas mask 插件imageIImageMask—图片遮罩选项使用图片作为遮罩源时配置overrideCanvasMaskOverride{color: true, opacity: false}粒子颜色/透明度覆盖选项pixelsCanvasMaskPixels{offset: 4, filter: a 0}像素采样选项position{x: number, y: number}{x: 50, y: 50}遮罩原点位置百分比50/50 即居中scalenumber1遮罩的缩放系数selectorstring—用于定位 canvas 元素的 CSS 选择器textTextMask—文字遮罩选项把文字渲染到 canvas 后作为遮罩注意README 中的 Option mapping 是通用模板文本实际使用中直接在options根级写入canvasMask键即可下方示例均为仓库内可直接运行的官方配置。enable 与三种遮罩源插件在运行时只处理enable true的情况CanvasMaskPluginInstance.init并且遮罩源按以下优先级选取只会使用其中一种image从image.src加载图片text把文字渲染到离屏 canvaselement/selector使用页面中已有的 canvas 元素。image图片遮罩ImageMask 类 只有一个src属性即图片地址支持跨域图片源码getImageData中设置了image.crossOrigin Anonymous。图片加载失败时对应 Promise 会被 reject见 utils/canvasUtils/src/Utils.ts。text文字遮罩TextMask 类 支持属性类型默认值说明textstring要渲染为遮罩的文本内容colorstring#000000文本颜色填充或描边色fillbooleantruetrue用fillText填充false用strokeText描边fontFontTextMask见下字体选项linesTextMaskLine见下多行文本选项fontFontTextMask 类family默认sans-serifsize默认100数字会被拼为100px也支持带单位的字符串另有style、variant、weight三个 CSS 字体描述属性默认空字符串。linesTextMaskLine 类separator默认\n按换行拆分多行spacing默认10行间距像素。文字渲染细节在 utils/canvasUtils/src/Utils.ts先按separator拆分文本用measureText逐行测量宽高再据此创建对应尺寸的离屏 canvas按fill决定fillText/strokeText。pixels像素采样CanvasMaskPixels 类 控制从遮罩源读取像素的方式offset默认4读取像素时的步长。对应 RGBA 每像素 4 个字节值为 4 即逐个像素完整采样增大 offset 会跳过更多字节显著减少采样点数、降低粒子数量与计算开销filter像素过滤函数(pixel: IRgba) boolean决定哪些像素允许生成粒子。默认实现为pixel.a 0即只要像素不透明就生成粒子。也支持传入全局函数名字符串源码会从globalThis中查找并校验是否为函数后使用。position 与 scale遮罩的布局position默认{x: 50, y: 50}表示遮罩中心在粒子画布中的百分比位置50% / 50%即居中scale默认1整体缩放遮罩尺寸放大/缩小粒子云的轮廓。在 utils.ts 中可以看到位置换算公式positionOffset (canvasSize * position) / 100 - maskSize * scale / 2即按百分比定位后再减掉半个遮罩尺寸实现以中心对齐。override粒子外观覆盖CanvasMaskOverride 类 决定粒子是否继承遮罩像素的颜色与透明度color默认true为true时粒子的填充色取遮罩像素的 RGBA 值通过paint.fill.color.value注入opacity默认false为true时粒子的透明度取遮罩像素的 alpha 值。从 utils.ts 的实现看颜色覆盖依赖引擎的paint选项透明度覆盖则写入粒子的opacity选项。若期望像素颜色真实生效需要确认当前使用的 bundle 包含对应的 paint 能力完整 bundle 已内置。可运行的完整示例示例一文字遮罩以下配置取自仓库内置示例 utils/configs/src/t/textMask.ts把 Hello 渲染为粒子形状并关闭颜色覆盖以展示随机颜色粒子await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { smooth: true, interactivity: { events: { onHover: { enable: true, mode: bubble } }, modes: { bubble: { distance: 40, duration: 2, opacity: 8, size: 15 } }, }, particles: { move: { direction: none, distance: 2, enable: true, speed: 1 }, number: { value: 600 }, color: { value: random }, shape: { type: [circle, square, triangle] }, size: { value: { min: 1, max: 3 } }, }, canvasMask: { enable: true, override: { color: false }, scale: 1, pixels: { filter: (pixel) pixel.a 0 }, position: { x: 70, y: 30 }, text: { color: #ff0000, font: { size: 500 }, text: Hello, }, }, background: { color: #0d0d0d }, }, });示例二图片遮罩以下配置取自 utils/configs/src/i/imageMask.ts。注意其filter会先剔除过暗的像素RGB 均小于 30 的像素不生成粒子再把不透明像素作为粒子来源await loadCanvasMaskPlugin(tsParticles); await tsParticles.load({ id: tsparticles, options: { smooth: true, particles: { move: { direction: none, distance: 10, enable: true, speed: 1 }, number: { value: 600 }, shape: { type: [circle, square, triangle] }, size: { value: { min: 3, max: 5 } }, }, canvasMask: { enable: true, scale: 5, pixels: { filter: (pixel) pixel.r 30 pixel.g 30 pixel.b 30 ? false : pixel.a 0, }, image: { src: https://particles.js.org/images/hdr/amongus_cyan.png }, }, background: { color: #0d0d0d }, }, });示例三已有 canvas 元素作为遮罩源官方选项文档 markdown/Options/Plugins/CanvasMask.md 给出的基础 JSON 配置展示了selector的用法——页面中必须存在一个 id 为my-mask-canvas的 canvas{ canvasMask: { enable: true, selector: #my-mask-canvas, position: { x: 50, y: 50 }, scale: 1 } }也可以用element直接传入HTMLCanvasElement实例需要脚本中已持有该元素引用。底层原理像素数据如何变成粒子插件注册与选项装载CanvasMaskPlugin 的needsPlugin判断options?.canvasMask?.enable是否为真只有启用时才通过loadOptions创建CanvasMask选项实例并装载用户配置。getPlugin会动态 import 并返回CanvasMaskPluginInstance实例插件 id 为canvas-mask。像素读取与粒子生成CanvasMaskPluginInstance.init()CanvasMaskPluginInstance.ts按图片 → 文字 → 已有 canvas的顺序读取像素图片getImageData(url, offset, render.settings)把图片绘制到临时 canvas 后读取像素文字getTextData(textOptions, offset, fill, render.settings)渲染文字后读取像素canvas 元素getCanvasImageData(context, canvas, offset)直接读取并默认clearRect清空原 canvas。这三者都返回CanvasPixelData { pixels: IRgba[][], width, height }。随后调用addParticlesFromCanvasPixelsutils.ts完成粒子生成其核心逻辑把全部像素索引随机洗牌Fisher-Yates shuffle保证粒子生成位置分散随机maxParticles Math.min(像素总数, particles.number.value)——粒子数量受全局particles.number.value约束不会超过遮罩像素数逐个弹出随机索引计算像素行列坐标经filter(pixel)过滤后把像素坐标乘以scale并加上positionOffset得到粒子实际位置根据override.color/override.opacity注入粒子外观选项最终调用container.particles.addParticle(pos, pOptions)。依赖与兼容性该插件依赖tsparticles/canvas-utils提供上述三个像素读取函数且以tsparticles/engine为 peer 依赖。加载函数内部会通过engine.checkVersion(__VERSION__)做版本校验因此务必保证插件与引擎版本匹配。常见陷阱Common pitfalls官方 README 明确列出了三类高频问题这里结合源码给出原因先调用tsParticles.load(...)再调用loadCanvasMaskPlugin(...)插件未注册时canvasMask配置不会被解析needsPlugin/loadOptions根本不生效粒子会按普通配置生成。务必保证loadCanvasMaskPlugin在tsParticles.load之前await完成启用高级选项前未确认 peer 依赖例如override.color依赖引擎的 paint 能力、override.opacity依赖 opacity 更新逻辑使用精简 bundleslim时需确认对应能力已内置或另行加载一次改动过多选项组不利于排错建议逐个调整position、scale、pixels.offset、pixels.filter、override等配置组便于快速定位回归原因。另外注意element必须是真的HTMLCanvasElement实例源码有instanceof校验传入字符串会被直接忽略。继续深入完整选项表与官方说明markdown/Options/Plugins/CanvasMask.md插件入口与注册逻辑plugins/canvasMask/src/index.ts、plugins/canvasMask/src/CanvasMaskPlugin.ts像素读取工具实现utils/canvasUtils/src/Utils.ts更多可运行的官方配置示例utils/configs/src/t/textMaskMultiline.ts、utils/configs/src/i/imageMaskRepulse.ts浏览器端加载演示demo/vanilla/views/index.pug、demo/vanilla/public/javascripts/playground.js /output文章【免费下载链接】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），仅供参考