tsParticles Next.js 集成实战基于 Pages Router 的 tsparticles/nextjs 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 仓库中的tsparticles/nextjs-legacy-demo为研究对象完整讲解如何在 Next.js Pages RouterLegacy 路由架构下使用tsparticles/nextjs集成粒子背景动画。文章覆盖 Demo 的脚本命令、Provider 与异步初始化机制、粒子组件渲染、主题插件切换、API 路由示例以及底层 wrapper 实现原理读者完成后可独立复刻一套可运行的 Next.js 粒子背景应用。背景Pages Router 与 tsparticles/nextjstsParticles仓库根目录是一个可高度定制的 JavaScript 粒子特效引擎支持粒子背景、彩带爆炸confetti与烟花fireworks等动画。在其生态中tsparticles/nextjs是针对 Next.js 的官方集成 wrapper提供 Next.js 优先的组件导出与客户端渲染处理。demo/nextjs-legacy是 tsParticles 仓库中基于Next.js Pages Router的官方示例应用其 README.md 明确说明Demo app fortsparticles/nextjsusing Next.js Pages Router.所谓 Legacy指相对于 App Routerapp/目录而言的传统 Pages Routerpages/目录路由架构。本 Demo 与仓库中的 App Router 示例 demo/nextjs 互为对照共同验证tsparticles/nextjs在两种路由模式下的兼容性。项目结构与文件职责该 Demo 的顶层结构如下详见 demo/nextjs-legacy路径职责pages/_app.js应用根组件挂载NextParticlesProvider并注册异步初始化回调pages/index.js首页渲染NextParticles粒子组件含明暗主题切换按钮pages/api/hello.js最小的 Next.js API 路由示例styles/globals.css全局样式重置 padding/margin、统一字体与盒模型styles/Home.module.css首页模块化样式package.json依赖与脚本声明next.config.jsNext.js 配置Turbopack 工作区根路径eslint.config.mjsESLint 扁平配置脚本命令从开发到生产部署README 列出了四个核心命令对应 package.json 中的 scriptspnpm run dev # 启动开发服务器next dev pnpm run lint # ESLint 检查eslint . --max-warnings 0 pnpm run build # 生产构建next build pnpm run start # 启动生产服务器next start值得注意的细节lint使用了--max-warnings 0即任何 warning 都会导致检查失败这是仓库 CI 质量门槛的一部分构建命令还包含build:ci变体用于 CI 环境由于该 Demo 处于 pnpm workspace 中dev/build/start依赖的next、react等包均通过workspace:*协议从仓库内部解析见 package.json 的 dependencies独立使用时请按正常 npm/pnpm 安装流程处理。核心机制一NextParticlesProvider 与异步初始化README 的 Notes 部分指出pages/_app.js负责承载NextParticlesProvider及异步 init 回调。实际实现如下demo/nextjs-legacy/pages/_app.jsimport ../styles/globals.css; import { NextParticlesProvider } from tsparticles/nextjs; const registerParticles async engine { const [{ loadSlim }, { loadThemesPlugin }] await Promise.all([ import(tsparticles/slim), import(tsparticles/plugin-themes), ]); await Promise.all([loadSlim(engine), loadThemesPlugin(engine)]); }; function MyApp({ Component, pageProps }) { return ( NextParticlesProvider init{registerParticles} Component {...pageProps} / /NextParticlesProvider ); } export default MyApp;这套模式的要点如下1. 一次初始化全局生效。registerParticles接收引擎实例engine通过动态import()并行加载tsparticles/slim精简版引擎加载器与tsparticles/plugin-themes主题插件然后调用各自的加载函数完成注册。动态导入保证了非核心模块的按需加载减小首屏包体积。2. Provider 必须放在应用根。在 Pages Router 中根位置就是pages/_app.js。从 wrapper 源码 wrappers/nextjs/lib/index.tsx 可以看到NextParticlesProvider是对tsparticles/react中ParticlesProvider的透传封装export function NextParticlesProvider({ children, init }: INextParticlesProviderProps): ReactNode { return ParticlesProvider init{init}{children}/ParticlesProvider; }官方 wrapper 的 README.md 也强调Provider 必须且只能在整个应用生命周期中渲染一次不要放进可能被卸载的组件中。3. init 回调的类型约定。INextParticlesProviderProps中的init类型为ParticlesPluginRegistrar即(engine) Promisevoid形式的插件注册函数由tsparticles/react导出见 wrappers/nextjs/lib/index.tsx。核心机制二NextParticles 渲染粒子与主题切换README 指出pages/index.js负责渲染NextParticles。实际代码demo/nextjs-legacy/pages/index.js展示了一个完整可运行的粒子配置import Head from next/head; import Image from next/image; import { NextParticles } from tsparticles/nextjs; import styles from ../styles/Home.module.css; import { useCallback, useMemo, useRef } from react; export default function Home() { const containerRef useRef(null); const particlesLoaded useCallback( container { containerRef.current container; globalThis.particlesContainer container; }, [containerRef], ); const options useMemo( () ({ fullScreen: { zIndex: -1, }, particles: { number: { value: 100 }, links: { enable: true }, move: { enable: true }, size: { value: 3 }, }, themes: [ { name: light, default: { value: true, auto: true, mode: light }, options: { background: { color: #ffffff }, particles: { paint: { fill: { color: { value: #000000 }, enable: true, }, }, links: { color: #000000 }, }, }, }, { name: dark, default: { value: true, auto: true, mode: dark }, options: { background: { color: #000000 }, particles: { paint: { fill: { color: { value: #ffffff }, enable: true, }, }, links: { color: #ffffff }, }, }, }, ], }), [], ); const lightTheme useCallback(() { containerRef.current?.loadTheme(light); }, []); const darkTheme useCallback(() { containerRef.current?.loadTheme(dark); }, []); // ... 页面其余 JSX ... return ( div className{styles.container} {/* 两个主题切换按钮 */} button onClick{lightTheme}Light/button button onClick{darkTheme}Dark/button {/* ... */} NextParticles idtsparticles options{options} particlesLoaded{particlesLoaded} / /div ); }几个值得展开的技术细节粒子配置options。这里配置了 100 个粒子、启用连线links、启用移动move、粒子尺寸为 3并将画布设为fullScreen全屏背景模式且zIndex: -1使粒子位于页面内容之后。配置对象通过useMemo缓存以避免每次渲染重建这与 tsParticles 引擎中 Options 体系见 engine/src/Options一一对应。主题插件themes。通过loadThemesPlugin注册的主题系统支持明暗两套配置default.auto配合mode: light/mode: dark会依据系统的prefers-color-scheme自动选择主题同时页面按钮通过容器实例的loadTheme(light)/loadTheme(dark)手动切换。容器实例由particlesLoaded回调捕获并存入containerRef这也是获取 tsParticles 容器句柄Container API的推荐方式。particlesLoaded 回调。当粒子容器初始化完成后触发参数为容器实例示例同时将其挂到globalThis.particlesContainer方便在浏览器控制台直接调试引擎 API。NextParticles 的客户端渲染本质。从 wrapper 源码 wrappers/nextjs/lib/index.tsx 可见NextParticles实际是经next/dynamic动态导入的tsparticles/react的Particles组件并显式设置ssr: falseconst DynamicParticles dynamic(() import(tsparticles/react).then(module module.Particles), { ssr: false, });这意味着粒子画布只在客户端渲染规避了 SSR 阶段操作window/canvas的问题——这正是tsparticles/nextjs存在的核心价值之一。核心机制三API 路由示例README 提到pages/api/hello.js是极简 API 路由样例demo/nextjs-legacy/pages/api/hello.jsexport default function handler(req, res) { res.status(200).json({ name: John Doe }) }它展示的是 Next.js Pages Router 下 API 路由的标准写法默认导出一个接收req/res的处理函数并返回 JSON。在真实项目中这里通常是后端数据接口粒子配置与 API 路由相互独立可共存于同一应用。工程配置Turbopack 与 ESLintnext.config.jsdemo/nextjs-legacy/next.config.js为本 Demo 的关键配置由于项目位于 pnpm workspace 内pnpm 将依赖放入仓库根部的虚拟 storeNext.js 的 Turbopack 需要被告知工作区根目录才能正确解析模块否则会报MODULE_UNPARSABLE如 Could not parse module .../node_modules/.pnpm/.../next/app.js错误const path require(path); module.exports { turbopack: { root: path.resolve(__dirname, .., ..), }, };root指向仓库根目录demo/nextjs-legacy向上两级。若你的 monorepo 结构层级不同需相应调整。eslint.config.mjsdemo/nextjs-legacy/eslint.config.mjs采用 ESLint 扁平配置flat config忽略.next/、out/、build/、node_modules/产物目录为 JS/JSX 文件声明浏览器与 Node 全局变量并启用 JSX 解析支持。从源码看 wrapper 工作原理Demo 依赖的tsparticles/nextjs完整实现在 wrappers/nextjs/lib/index.tsx仅约 20 行核心逻辑高度聚焦导出NextParticlesProvider对ParticlesProvider的透传职责是持有并执行一次性的 init 异步注册流程导出NextParticles对Particles的动态导入包装ssr: false保证仅客户端渲染重新导出IParticlesProps与ParticlesPluginRegistrar类型方便使用方做类型标注。其 peerDependencies 要求next 13.0.0、react 18.0.0见 wrappers/nextjs/package.json而本 Demo 使用 Next.js 16、React 19处于受支持范围内。与 App Router 用法的对照如果迁移到 App Router 架构官方 wrapper 文档wrappers/nextjs/README.md给出对照写法组件文件顶部需加use clientNextParticlesProvider挂到根layout.tsx页面中直接组合NextParticles即可init 回调内容与 Pages Router 版本完全一致。本 Demo 的pages/_app.js与 App Router 示例 demo/nextjs 共同验证了同一套 API 在两种路由模式下的可用性。小结通过demo/nextjs-legacy可以总结出在 Next.js Pages Router 中集成 tsParticles 的完整套路在pages/_app.js挂载NextParticlesProviderinit 回调中动态加载并注册所需引擎模块与插件在任意页面使用NextParticles组件并传入options通过particlesLoaded拿到容器句柄需要响应式配色时加载tsparticles/plugin-themes并配置themes数组结合loadTheme()手动切换在 pnpm monorepo 中运行时为 Turbopack 配置正确的工作区root以避免模块解析错误。本文涉及的关键源码均位于仓库内可进一步阅读pages/_app.js、pages/index.js、wrappers/nextjs/lib/index.tsx 及引擎 Options 定义目录 engine/src/Options。【免费下载链接】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），仅供参考