Riot.js 中集成 tsParticles 粒子动画riot-particles-demo 的启动、测试与构建实战指南【免费下载链接】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 仓库内的demo/riotRiot.js 演示项目为骨架完整讲解如何在一个基于 Riot 10 的应用中集成tsparticles/riot组件从三条核心命令npm start/npm test/npm run build出发逐层拆解 webpack 开发服务器、Mocha 单元测试与生产构建的配置细节并深入wrappers/riot的组件源码说明粒子引擎初始化、配置热切换与容器自动清理的底层原理。读完本文你将掌握在 Riot.js 项目中接入 tsParticles 并完成开发调试、自动化测试与打包发布的完整工作流。项目概览riot-particles-demo 的目录结构demo/riot是 tsParticles 仓库中的一个完整、可独立运行的 Riot.js 演示应用其package.json中声明为tsparticles/riot-demo私有包。从目录结构看它遵循 Riot 项目的常见组织方式demo/riot/package.json项目依赖与start/test/build等脚本定义demo/riot/src/index.js应用入口负责注册全局组件并挂载demo/riot/src/index.htmlHtmlWebpackPlugin 使用的页面模板demo/riot/src/components/Riot 组件目录含global/my-component、global/sidebar与includes/user三组组件及对应的.spec.js测试demo/riot/webpack.config.js开发服务器、.riot加载器与代码分割配置demo/riot/style.css演示页面样式。在依赖方面package.json同时引用了tsparticles/engine、tsparticles/riot、tsparticles提供loadFull全量加载器与tsparticles/configs内置预设配置并通过 pnpm workspace 指向仓库内的本地包。Riot 相关依赖包括riot^10.1.4、riotjs/compiler、riotjs/register、riotjs/webpack-loader以及用于热更新、懒加载和路由的riotjs/hot-reload、riotjs/lazy、riotjs/route。该演示应用核心展示的是riot-particles组件一个带有 Switch Config 按钮的页面点击即可在configs.basic与configs.star两套粒子配置间动态切换直观体现 tsParticles 配置的响应式更新能力。快速开始用 npm start 启动开发服务器readme.md给出的第一条命令是npm start它对应 demo/riot/package.json 中的脚本start: webpack serve --mode development --hot --port 3003即通过 webpack-dev-server 以开发模式启动并开启HMR 热模块替换监听3003 端口。结合 demo/riot/webpack.config.js 可以看到完整的开发链路entry指向./src/index.js输出为[name].bundle.js并启用source-map便于调试.riot文件由riotjs/webpack-loader编译options.hot: true与--hot配合实现组件级热更新devServer.hot与devServer.open均为true启动后自动打开浏览器devServer.historyApiFallback将未知路由回退到index.htmlHtmlWebpackPlugin以 demo/riot/src/index.html 为模板生成页面。启动后浏览器打开http://localhost:3003页面标题为 My Riot App主体是my-component内含粒子画布与切换按钮和sidebar两个全局组件。应用入口与组件注册npm start加载的入口 demo/riot/src/index.js 展示了 Riot 10 中注册与挂载组件的标准写法import riotjs/hot-reload; import { mount, register } from riot; import RiotParticles from ../../../wrappers/riot/src/riot-particles.riot; import MyComponent from ./components/global/my-component/my-component.riot; import Sidebar from ./components/global/sidebar/sidebar.riot; import User from ./components/includes/user/user.riot; register(my-component, MyComponent); register(sidebar, Sidebar); register(user, User); register(riot-particles, RiotParticles); // mount all the global components found in this page mount([data-riot-component]);值得注意demo 直接以相对路径../../../wrappers/riot/src/riot-particles.riot导入粒子组件源码而非通过 npm 包名这是为了在 monorepo 内联调试 wrapper 本身。同时 webpack.config.js 中配置了别名将tsparticles/riot也解析到同一份.riot源文件避免产生重复的模块实例alias: { tsparticles/riot$: path.resolve(__dirname, ../../wrappers/riot/src/riot-particles.riot), }组件通过 HTML 中data-riot-component属性标记由mount()统一挂载模板见 demo/riot/src/index.html。组件实操初始化引擎与渲染粒子my-component是演示粒子集成的核心组件源码位于 demo/riot/src/components/global/my-component/my-component.riotriot-particles idtsparticles options{particlesConfig} particlesLoaded{particlesLoaded}/ script import { initParticlesEngine } from tsparticles/riot; import { loadFull } from tsparticles; import configs from tsparticles/configs; let toggle false; export default { particlesConfig: configs.basic, particlesLoaded: (container) console.log(container), onBeforeMount() { // Riot can be used server-side; guard initialization to client only. if (typeof window ! undefined) { initParticlesEngine(async (engine) { await loadFull(engine); console.log(particles initialized); }); } }, switchConfig() { toggle !toggle; this.particlesConfig toggle ? configs.star : configs.basic; this.update(); }, } /script这段代码揭示了三个关键实践引擎初始化必须在组件挂载前完成一次initParticlesEngine接收一个回调回调中通过loadFull(engine)注册全部插件/交互/形状。demo 把它放在onBeforeMount并守卫了typeof window ! undefined——这是为兼容 Riot 的 SSR 场景服务端渲染时不存在window不应初始化浏览器粒子引擎。particlesLoaded回调粒子容器创建成功后触发demo 中仅console.log(container)输出容器实例实际项目中可用于读取粒子数量、监听事件或联动其他逻辑。配置切换switchConfig在configs.basic与configs.star两套内置预设之间切换配合this.update()驱动 Riot 重新渲染从而触发riot-particles的onUpdated生命周期并重载粒子。tsparticles/configs提供了大量这类开箱即用的预设配置见 utils/configs适合快速验证效果。测试npm test 与 Riot 组件单元测试readme.md的第二条命令是npm test对应脚本为test: nyc --require esm --require jsdom-global/register --require riotjs/register mocha src/**/*.spec.js这是一条组合式测试命令逐个拆解如下mocha测试运行器收集src/**/*.spec.js下的所有测试文件--require riotjs/register让 Node 环境能够直接编译加载.riot文件--require jsdom-global/register注入 jsdom 全局 DOM 环境使组件可以在无浏览器环境下挂载Riot 组件依赖 DOM API--require esm启用 ESM 模块解析nyc覆盖率收集器另有cov输出 text-lcov 格式、cov-html生成 HTML 报告。测试用例解析以 demo/riot/src/components/global/my-component/my-component.spec.js 为例这是 Riot 官方推荐的component()挂载式测试写法import MyComponent from ./my-component.riot import { expect } from chai import { component } from riot describe(My Component Unit Test, () { const mountMyComponent component(MyComponent) it(The component properties are properly rendered, () { const div document.createElement(div) const component mountMyComponent(div, { message: hello }) expect(component.$(p).innerHTML).to.be.equal(hello) }) })其思路是用component(MyComponent)获得可挂载的工厂函数向document.createElement创建的div中挂载组件并传入 props再通过component.$(p)查询渲染后的 DOM 断言结果。sidebar.spec.js与user.spec.js采用同样的模式验证各自组件的状态与 prop 渲染。在package.json中还有一条相关脚本prepublishOnly: npm test即发布前自动执行测试作为质量门槛。覆盖率相关命令cov/cov-html可基于nyc生成 lcov 格式或 HTML 报告便于接入 CI 或本地查看。构建npm run build 生产打包readme.md的第三条命令是npm run build对应脚本build: webpack --mode production, build:ci: webpack --mode productionbuild与build:ci行为一致均为生产模式打包后者面向 CI 场景名称自解释。结合 webpack.config.js 可看到生产构建的完整形态产物输出到dist/目录output.clean: true会在每次构建前清空旧产物MiniCssExtractPlugin将 CSS 抽取为独立文件与开发模式内联注入不同optimization.splitChunks配置了 vendor 分包defaultVendors缓存组把node_modules依赖拆为公共 chunkdefault缓存组对多 chunk 引用的模块进行合并同时启用了runtimeChunk提取运行时代码以提升长期缓存命中率。生产模式下 webpack 默认启用压缩与 tree-shaking最终dist/app.bundle.js、runtime.bundle.js及样式文件即为可直接部署的静态资源。底层原理tsparticles/riot 组件源码剖析演示项目中的riot-particles组件本体位于 wrappers/riot/src/riot-particles.riot其官方文档见 wrappers/riot/README.md。该组件对外暴露了两个关键 API 与完整的生命周期管理理解它就能明白 demo 各条命令背后的机制。initParticlesEngine一次性引擎初始化export async function initParticlesEngine(cb) { if (initialized) return; if (initPromise) { if (initCallback ! cb) { throw new Error(initParticlesEngine callback must be stable across the app lifecycle.); } await initPromise; return; } initCallback cb; initPromise (async () { if (cb) await cb(tsParticles); await tsParticles.init(); initialized true; })().catch((error) { initPromise undefined; initCallback undefined; initialized false; throw error; }); await initPromise; }从源码可以总结出三条约束幂等性重复调用时直接返回不会重复初始化若初始化进行中则等待同一个initPromise回调稳定性若第二次传入的回调与首次不同会抛出initParticlesEngine callback must be stable across the app lifecycle.错误——这正是 demo 把初始化放在组件onBeforeMount、且整个应用只调用一次的原因失败可重试初始化失败会重置内部状态并重新抛出错误允许下次调用重试。组件还导出isParticlesEngineInitialized()与waitForParticlesEngineInitialization()两个辅助函数供挂载前确认引擎状态。生命周期挂载、更新与自动清理riot-particles.riot的默认导出实现了三个生命周期钩子onMounted先await waitForParticlesEngineInitialization()等待引擎就绪若未调用过initParticlesEngine则抛出initParticlesEngine(...) must be called once before mounting riot-particles / components.。随后调用loadParticles内部通过tsParticles.load({ id, options, url })创建容器。onUpdated对比新旧 propsid/options/url任一变化时先destroy()旧容器再重新加载仅theme变化时调用loadTheme应用主题。onUnmounted自动执行container?.destroy()销毁粒子容器确保组件从 DOM 移除后不会遗留后台动画这也是 wrapper 文档中 Cleanup 一节的实现基础。loadParticles中还使用自增的loadId处理异步竞态若加载期间 props 再次变化产生新的loadId旧容器会被立即销毁避免过期容器残留。Props 与响应式行为根据 wrappers/riot/README.mdriot-particles支持的 props 如下Prop类型说明idstring粒子容器的 DOM idoptionsobject粒子配置对象urlstring远程 JSON 配置文件地址themestring要应用的主题名需要tsparticles/plugin-themes插件支持particlesLoadedfunction粒子加载完成回调接收(container?: Container)响应式更新规则与源码逻辑一一对应修改id销毁当前容器用新 id 重建修改options或url销毁当前容器并按新配置重载粒子修改theme直接调用loadTheme平滑切换不重建容器若未安装tsparticles/plugin-themes该操作是安全的 no-op不会报错。demo 中switchConfig切换options即触发了上述销毁 重载流程这也是为什么按钮点击后粒子样式会整体刷新。从 demo 到自有项目最小集成清单结合demo/riot与wrappers/riot在自有 Riot.js 项目中接入 tsParticles 的最小步骤可归纳为安装依赖tsparticles/riot组件 任意加载器如tsparticles的loadFull或更精简的tsparticles/slim初始化引擎在应用入口或首个组件onBeforeMount中调用一次initParticlesEngine(async (engine) await loadFull(engine))并保证回调稳定注册组件register(riot-particles, RiotParticles)引入自tsparticles/riot使用组件传入id与options或url需要时通过particlesLoaded拿到容器实例配置构建参照 demo/riot/webpack.config.js 为.riot文件启用riotjs/webpack-loader保障质量按 demo 的测试模式用riotjs/register jsdom Mocha 编写组件测试并可通过npm run build产出生产包。至此从npm start的即时反馈、npm test的组件级验证到npm run build的产物交付Riot.js 与 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），仅供参考