tsParticles Export Video 插件指南：将粒子动画导出为 WebM/MP4 视频-开发者社区

tsParticles Export Video 插件指南：将粒子动画导出为 WebM/MP4 视频

【免费下载链接】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/plugin-export-video是 tsParticles 官方提供的视频导出插件，它基于浏览器原生MediaRecorder与HTMLCanvasElement.captureStream()能力，把正在运行的粒子动画画布实时录制为视频 Blob，从而无需安装任何额外依赖即可将粒子效果、彩带爆炸或烟花动画保存成 WebM、OGG、MP4 等格式。阅读本文后，你将掌握该插件的完整接入流程（CDN 与模块化两种方式）、可配置参数（fps、duration、mimeType），以及它在引擎中的导出调用链与浏览器兼容性边界。

插件是什么：职责与架构定位

@tsparticles/plugin-export-video是 tsParticles 众多"导出插件"之一，它本身不修改粒子选项体系，而是向引擎注册一个容器级插件（IContainerPlugin），为Container.export(type, options)提供video类型的导出能力。

从源码结构看，该插件由四个核心文件组成（见 plugins/exports/video/src）：

ExportVideoPlugin.ts：实现IPlugin接口，插件 ID 固定为"export-video"，needsPlugin()始终返回true（即只要注册就生效），并通过动态import懒加载插件实例；
ExportVideoPluginInstance.ts：实现IContainerPlugin，真正执行画布捕获与MediaRecorder录制逻辑；
IExportVideoData.ts：导出参数类型定义；
index.ts / index.lazy.ts / browser.ts：包入口，导出loadExportVideoPlugin加载函数。

加载函数的核心工作非常直接：在 index.ts 中调用engine.checkVersion(__VERSION__)做引擎版本兼容性校验，然后通过engine.pluginManager.register(...)将插件注册进引擎。而 index.lazy.ts 提供了"延迟加载"变体——只有当注册时才会真正import插件类，适合对首屏包体积敏感的场景。

安装与快速接入清单

根据 README.md，接入只需三步：

安装（或通过 CDN 引入）@tsparticles/engine；
在调用tsParticles.load(...)之前调用包加载函数loadExportVideoPlugin(...)；
按需通过引擎的导出 API 触发视频导出。

包本身通过 npm / yarn 安装，安装命令见下文。其package.json声明了唯一的 peer 依赖@tsparticles/engine（workspace:*），并提供"."与"./lazy"两个导出入口（分别对应常规与懒加载加载器），版本为 4.3.3。

CDN / Vanilla JS / jQuery 方式

在原生 JavaScript（或 jQuery）场景下，引入tsparticles.plugin.export.video.min.js这一个文件即可。该文件在全局挂载了加载函数loadExportVideoPlugin（见 browser.ts 中的globalObject.loadExportVideoPlugin = loadExportVideoPlugin赋值）。

脚本加载完成后，即可初始化tsParticles并注册插件：

(async () => { await loadExportVideoPlugin(); await tsParticles.load({ id: "tsparticles", options: {/* options */}, }); })();

ESM / CommonJS 方式

该包同时兼容 ES Module 与 CommonJS。先安装依赖：

$ npm install @tsparticles/plugin-export-video

或：

$ yarn add @tsparticles/plugin-export-video

CommonJS 用法：

const { tsParticles } = require("@tsparticles/engine"); const { loadExportVideoPlugin } = require("@tsparticles/plugin-export-video"); (async () => { await loadExportVideoPlugin(); })();

ESM 用法：

import { tsParticles } from "@tsparticles/engine"; import { loadExportVideoPlugin } from "@tsparticles/plugin-export-video"; (async () => { await loadExportVideoPlugin(); })();

注意：在 Webpack / Vite 等打包工具中，如果你的目标是减小主包体积，也可以从@tsparticles/plugin-export-video/lazy导入加载函数，把插件类的解析推迟到运行时。

触发视频导出：参数与调用链

导出参数（IExportVideoData）

该插件没有独立的"根选项键"，而是通过引擎导出 API 的data参数传递配置。参数由 IExportVideoData.ts 定义，全部为可选：

参数	类型	说明	默认值
`duration`	`number`	导出视频时长（秒）	`5`（源码中`defaultDuration = 5`）
`fps`	`number`	录制帧率	取`container.actualOptions.fpsLimit`
`mimeType`	`string`	输出视频的 MIME 类型	浏览器支持列表中的第一个类型

调用方式

tsParticles.load(...)会返回Container实例，而引擎在 Container.ts 中提供了统一的export(type, options)方法：它遍历容器内所有已注册插件，找到支持指定type的插件并调用其export方法，返回ExportResult（定义见 ExportResult.ts，含supported、blob、error字段），最终把第一个"支持"的插件的blob返回给调用方；若没有插件支持该类型，则记录错误日志并返回undefined。

因此实际触发录制的方式是：

import { tsParticles } from "@tsparticles/engine"; import { loadExportVideoPlugin } from "@tsparticles/plugin-export-video"; (async () => { await loadExportVideoPlugin(); const container = await tsParticles.load({ id: "tsparticles", options: { fpsLimit: 60, particles: { number: { value: 80 }, move: { enable: true }, }, }, }); // 录制 5 秒视频（默认时长），帧率跟随 fpsLimit const blob = await container.export("video", { duration: 5, fps: 60 }); if (blob) { const url = URL.createObjectURL(blob); const a = document.createElement("a"); a.href = url; a.download = "particles.webm"; a.click(); URL.revokeObjectURL(url); } })();

底层录制原理

在 ExportVideoPluginInstance.ts 的#exportVideo私有方法中，录制流程如下：

从container.canvas.domElement取得<canvas>元素；
调用element.captureStream(data.fps ?? container.actualOptions.fpsLimit)获得媒体流——帧率优先取用户传入的fps，未传则回退到粒子配置的fpsLimit；
用new MediaRecorder(stream, { mimeType })创建录制器；
监听dataavailable事件收集数据块（chunk），监听stop事件时将所有 chunk 合并为一个Blob（type 为所选 MIME 类型）并 resolve；
recorder.start()后通过setTimeout在data.duration ?? 5秒后调用recorder.stop()结束录制。

值得注意的是，整个录制完全发生在浏览器端，不需要服务端转码，导出的结果是内存中的Blob对象，你可以自由决定如何展示（如<video>预览）或下载（如上面的URL.createObjectURL+ 模拟点击）。

MIME 类型与编解码器支持：浏览器能力探测

由于不同浏览器对视频容器的支持差异很大，插件在构造时（ExportVideoPluginInstance.ts）会通过MediaRecorder.isTypeSupported()探测当前环境的真实能力，而不是硬编码输出格式。

它探测的容器类型包括：

video/webm
video/ogg
video/mp4
video/x-matroska（MKV）

对每种容器，又会组合以下编解码器逐一验证（含大小写变体）：

vp9, vp8, avc1, av1, h265, h265, h264, opus, pcm, aac, mpeg, mp4a

最终得到"当前浏览器确实支持"的 MIME 类型列表，并保存在实例的#supportedTypes中；当用户未指定mimeType时，插件默认取该列表的第一个元素（源码中firstIndex = 0）。这意味着：在不传mimeType的情况下，实际输出格式取决于浏览器（例如 Chrome 通常首选video/webm;codecs=vp9，而 Safari 可能偏向video/mp4）。如果你想确保下载文件的扩展名正确，建议在导出前自行判断blob.type，或显式传入你确认可用的mimeType。

另外，源码中对MediaRecorder.isTypeSupported的探测覆盖了常见大小写形式（vp9/VP9），并注释指出codecs:（冒号分隔）的变体是误报来源，因此被排除在外——这保证了能力探测的准确性。

常见陷阱与排查建议

README 明确列出了三条使用注意事项，结合源码可以进一步解释其成因：

在loadExportVideoPlugin(...)之前调用tsParticles.load(...)：这是最常见的错误。Container.export("video", ...)只会在已注册的插件中寻找video导出支持；如果加载函数尚未执行（engine.pluginManager.register未完成），容器内就没有ExportVideoPluginInstance，引擎会走完循环后记录Export plugin with type video not found错误并返回undefined。务必保证加载函数await完成后再加载配置。
开启高级选项前确认 peer 依赖：插件以@tsparticles/engine为 peer 依赖（见 package.json），需要保证引擎版本与插件版本兼容；loadExportVideoPlugin内部的engine.checkVersion(__VERSION__)会做版本校验，版本不匹配时会抛出错误。
一次只修改一组选项以快速定位回归：由于fps、duration、mimeType相互影响录制结果（例如强制指定了浏览器不支持的mimeType时，MediaRecorder构造会直接抛异常），排查问题时建议逐个调整参数，避免多个变量叠加导致难以定位。

总结

@tsparticles/plugin-export-video是一个"薄而聚焦"的浏览器端视频导出插件：通过 index.ts 注册、由 ExportVideoPluginInstance.ts 完成captureStream+MediaRecorder录制，并借助 Container.export 与 ExportResult 融入引擎统一的导出体系。使用时只需牢记"先加载插件、再加载粒子配置、最后调用container.export("video", {...})"的顺序，并理解 MIME 类型由浏览器能力探测决定这一前提，即可稳定地将任意 tsParticles 动画导出为可下载的视频文件。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考