用 cra-template-particles 快速搭建带 tsParticles 粒子特效的 React 应用：Create React App 官方模板完全指南-开发者社区

用 cra-template-particles 快速搭建带 tsParticles 粒子特效的 React 应用：Create React App 官方模板完全指南

【免费下载链接】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

本文以 templates/react/README.md 为核心文档，结合 templates/react 模板目录、wrappers/react/README.md 以及模板源码展开讲解，帮助读者掌握如何通过 Create React App（CRA）官方模板cra-template-particles在数秒内初始化一个自带可交互粒子背景的 React 项目，并深入理解模板生成的目录结构、particles.json配置项与ParticlesProvider初始化机制，进而能够独立完成粒子特效的定制。

一、模板是什么：为 React tsParticles 定制的 CRA 官方模板

cra-template-particles是 tsParticles 项目为 React 官方维护的 Create React App 模板，位于仓库的 templates/react 目录。它把「创建一个 CRA 应用」和「集成 React tsParticles 组件」两个步骤合并为一步：使用该模板初始化项目后，你会得到一个开箱即用、带有全屏粒子背景动画的 React 应用。

从 templates/react/package.json 可以看出，该模板包的元信息包括：

包名：cra-template-particles，版本与 tsParticles 主版本保持同步（当前仓库内为4.3.3）；
描述为 "Official React tsParticles template"；
发布内容（files）仅包含template目录与template.json两个部分，其中template/是真正会拷贝到用户新项目中的脚手架文件，template.json负责声明新项目默认安装的依赖；
发布前的build脚本会执行 templates/react/scripts/prebuild.js，把 monorepo 工作区中的workspace:*依赖版本解析成具体版本号，再写入template.json，从而保证用户通过 npm/yarn 安装模板时拿到的是可解析的真实版本。

需要特别留意的是，templates/react/package.json 中同时标注了该包的deprecated状态：由于 Create React App 本身已停止维护，官方建议改用@tsparticles/template-scaffold，并通过npm create tsparticles使用基于 Vite 的新模板。因此，本文讲解的 CRA 模板适用于仍然基于 Create React App 的存量项目或教学场景；新项目更推荐使用官方新的 Vite 脚手架流程。

二、三步上手：用一条命令生成带粒子的 React 应用

根据 templates/react/README.md，使用该模板创建项目非常简单。在安装好 Node.js 与 npm（或 yarn）的前提下，执行以下任意一条命令：

npx create-react-app my-app --template particles # 或者使用 yarn yarn create react-app my-app --template particles

其中my-app是你要创建的项目目录名，--template particles指定使用cra-template-particles模板。README 同时说明：如果不显式指定模板（例如省略--template参数），该模板会被作为默认模板使用。

命令执行完毕后，进入项目目录并启动开发服务器：

cd my-app npm start

浏览器访问http://localhost:3000即可看到粒子动画背景。整个流程无需手动安装@tsparticles/react、编写初始化代码或配置粒子参数——模板已经替你完成了这一切。

三、生成的模板项目结构：每一个文件的作用

通过--template particles创建的项目，其源文件来自仓库中的 templates/react/template 目录。与普通 CRA 模板相比，差异集中在src目录：

src/ ├── App.css # 应用样式（含粒子层叠样式） ├── App.js # 根组件：挂载 <Particles> 并渲染页面内容 ├── App.test.js # 默认的 React 测试（渲染 learn react 链接） ├── index.css ├── index.js # 入口：用 <ParticlesProvider> 包裹根组件 ├── logo.svg ├── particles.json # ★ tsParticles 粒子配置（模板的核心） ├── serviceWorker.js # CRA 默认的 PWA Service Worker └── setupTests.js

模板在 templates/react/template.json 中为新建项目预置了如下依赖：

{ "package": { "dependencies": { "@tsparticles/react": "^4.3.3", "@tsparticles/engine": "^4.3.3", "tsparticles": "^4.3.3", "tslib": "^2.8.1" } } }

@tsparticles/react：React 组件封装，提供<Particles>与<ParticlesProvider>；
@tsparticles/engine：tsParticles 核心引擎，提供Engine、Container、ISourceOptions等类型与运行时；
tsparticles：完整功能 bundle（loadFull），模板用它注册全部粒子功能；
tslib：TypeScript 运行时辅助库。

在 monorepo 构建时，这些版本号由 scripts/prebuild.js 从 wrappers/react/package.json、engine/package.json 与 bundles/full/package.json 中读取并回填，保证模板与主仓库版本严格一致。

3.1 入口文件：ParticlesProvider 与引擎初始化

template/src/index.js 展示了模板的正确挂载方式：

import React from "react"; import ReactDOM from "react-dom/client"; import "./index.css"; import App from "./App"; import * as serviceWorker from "./serviceWorker"; import { ParticlesProvider } from "@tsparticles/react"; import { registerParticles } from "./particlesInit"; const root = ReactDOM.createRoot(document.getElementById("root")); root.render( <React.StrictMode> <ParticlesProvider init={registerParticles}> <App /> </ParticlesProvider> </React.StrictMode> ); serviceWorker.unregister();

这里的关键是<ParticlesProvider init={registerParticles}>：

ParticlesProvider接收一个异步init回调，该回调在应用生命周期内只执行一次，负责向引擎注册所需的插件/功能模块；
根据 wrappers/react/README.md 的说明，ParticlesProvider应放在应用的根节点（如index.jsx、main.tsx），不要放进会条件挂载/卸载的组件中，否则引擎初始化可能只在首次生效，导致后续重新挂载时容器管理异常；
registerParticles的典型实现可在 demo/react/src/particlesInit.js 中看到：通过import("@tsparticles/slim")动态加载loadSlim并执行loadSlim(engine)。模板项目因依赖中预置了完整的tsparticlesbundle，其初始化逻辑对应使用loadFull注册全部功能（这也是模板在 template.json 中同时包含tsparticles的原因）。

3.2 根组件：以 options 方式挂载 Particles

template/src/App.js 是最简用法示例：

import React from "react"; import Particles from "@tsparticles/react"; import logo from "./logo.svg"; import "./App.css"; import particlesOptions from "./particles.json"; function App() { return ( <div className="App"> <Particles options={particlesOptions}/> <header className="App-header"> <img src={logo} className="App-logo" alt="logo"/> <p> Edit <code>src/App.js</code> and save to reload. </p> <p> Edit <code>src/particles.json</code> to customize Particles, then save to reload. </p> ... </header> </div> ); } export default App;

模板采用「Options 对象」方式：将粒子配置抽离到独立的 particles.json，通过import particlesOptions from "./particles.json"引入，再以<Particles options={particlesOptions}/>传入。这样粒子参数与组件代码完全解耦——修改特效只需编辑 JSON，保存后热更新即可生效，无需改动业务组件。

根据 wrappers/react/README.md，<Particles>组件还支持以下常用 props：

Prop	类型	说明
`id`	string	粒子画布元素的 id
`options`	object	粒子实例的配置对象
`url`	string	远程配置地址，组件会通过 AJAX 请求加载
`style`	object	画布元素的行内样式
`className`	string	画布容器的 class 名
`particlesLoaded`	function	容器加载完成后的回调，接收`(container?: Container)`

也就是说，除了模板演示的options方式，你还可以使用<Particles url="https://example.com/particles.json"/>从远程加载配置，两种方式都受支持。

四、particles.json 逐项详解：模板默认粒子效果的完整配置

template/src/particles.json 是模板的核心配置，下面逐段解释每一项的作用与取值含义，方便直接修改复用：

{ "background": { "color": "#282c34" }, "interactivity": { "events": { "onClick": { "enable": true, "mode": "push" }, "onHover": { "enable": true, "mode": "repulse" }, "resize": true }, "modes": { "push": { "quantity": 4 }, "repulse": { "distance": 200, "duration": 0.4 } } }, "particles": { "color": { "value": "#ffffff" }, "links": { "color": "#ffffff", "distance": 150, "enable": true, "opacity": 0.5, "width": 1 }, "collisions": { "enable": true }, "move": { "direction": "none", "enable": true, "outModes": { "default": "bounce" }, "random": false, "speed": 6, "straight": false }, "number": { "density": { "enable": true }, "value": 80 }, "opacity": { "value": 0.5 }, "shape": { "type": "circle" }, "size": { "random": true, "value": 5 } } }

4.1 background：背景颜色

background.color设置为#282c34（Create React App 默认的深蓝灰背景色），粒子层会覆盖在整个应用背景上，与 CRA 初始页面的配色保持一致。

4.2 particles.number：粒子数量

value: 80：画布中初始粒子数为 80 个；
density.enable: true：开启密度自适应，粒子数量会依据画布面积自动调整，屏幕越大粒子越多，保证视觉密度均匀。

4.3 particles.shape：粒子形状

type: "circle"表示粒子为圆形。tsParticles 支持多种形状（如square、star、heart、emoji及自定义 Path 等），修改此处即可切换外观。

4.4 particles.size：粒子大小

value: 5：基础尺寸为 5px；
random: true：尺寸在基础值上下随机分布，形成大小错落的层次感。

4.5 particles.color：粒子颜色

value: "#ffffff"为白色粒子，与深色背景形成高对比度。

4.6 particles.opacity：透明度

value: 0.5，粒子半透明显示，叠加后更有朦胧的层次感。

4.7 particles.links：粒子连线

links是模板默认效果的核心视觉元素：

enable: true：开启粒子之间的连线；
color: "#ffffff"：连线颜色为白色；
distance: 150：距离小于 150px 的粒子对之间才会绘制连线；
opacity: 0.5：连线透明度；
width: 1：连线宽度 1px。

4.8 particles.move：运动与边界行为

enable: true：粒子持续运动；
speed: 6：移动速度；
direction: "none"：方向随机，无固定朝向；
straight: false：粒子不沿直线运动（配合 random 方向产生自然游走）；
random: false：速度不随机化；
outModes.default: "bounce"：粒子运动到画布边缘时反弹回画布内，而不是被清除或消失。

4.9 particles.collisions：粒子碰撞

collisions.enable: true开启粒子间的物理碰撞，避免粒子互相穿过重叠。

4.10 interactivity：交互响应

交互配置分为events（触发事件）与modes（触发后执行的行为）：

onClick.enable: true+mode: "push"：点击画布时新增粒子，modes.push.quantity: 4表示每次点击追加 4 个粒子——这是一个非常直观的"点击爆粒子"交互；
onHover.enable: true+mode: "repulse"：鼠标悬停时粒子被推开，modes.repulse.distance: 200为排斥作用半径，duration: 0.4为排斥效果持续时间（秒）；
resize: true：窗口尺寸变化时自动重绘画布与粒子布局。

4.11 与官方示例配置的对照

将模板的particles.json与 wrappers/react/README.md 中给出的 JS/TS 内联配置示例对比可以发现，二者在参数结构上完全一致（背景色、fpsLimit、detectRetina、interactivity、particles等），区别仅在于：

模板使用独立 JSON 文件承载配置；
内联示例使用useMemo(() => ({...}), [])保证 options 引用稳定，避免组件重复创建实例，并额外提供了fpsLimit: 120（帧率上限）与detectRetina: true（视网膜屏高清渲染）两个全局选项，可作为升级模板配置时的参考；
内联示例中的size.value写成{ min: 1, max: 5 }区间形式，等价于模板size.random: true, value: 5的随机效果，可见同一效果有等价写法。

五、新建项目中的可用脚本（来自模板 README）

模板随 CRA 自带的标准脚本（详见 template/README.md）：

npm start：启动开发服务器，默认地址http://localhost:3000，代码保存后自动热更新，控制台会显示 lint 错误；
npm test：以交互监听模式运行测试（模板自带 App.test.js，验证首页能渲染出 "learn react" 链接）；
npm run build：生产构建，输出到build目录，产物经过压缩并带内容哈希文件名，可直接部署；
npm run eject：弹出 CRA 内部配置（webpack、Babel、ESLint 等），此操作不可逆，模板 README 明确建议非必要不执行。

六、自定义与迁移建议

6.1 修改粒子效果的三条路径

基于模板生成的工程，定制特效有且不限于以下三种方式：

直接编辑src/particles.json：改颜色、数量、速度、连线距离、交互行为等，保存即热更新（模板 App.js 中的提示文案也是这么引导的）；
改用内联 Options 对象：参照 wrappers/react/README.md 中的useMemo写法，把配置写在组件内，便于使用 TypeScript 类型ISourceOptions获得编译期校验，或引用MoveDirection、OutMode等枚举常量；
切换加载的 bundle：模板默认通过tsparticles（loadFull）注册全部功能，若只需基础效果，可在particlesInit中改用loadSlim（来自@tsparticles/slim）或loadBasic（来自@tsparticles/basic），减小最终打包体积。

6.2 面向新项目的迁移路径

由于 Create React App 已停止维护，templates/react/package.json 明确标注该模板为废弃状态（deprecated），官方推荐：

新项目改用@tsparticles/template-scaffold；
通过npm create tsparticles使用基于 Vite 的模板（仓库 templates/scaffold 即对应脚手架资源）。

对于存量 CRA 项目，迁移的核心工作就是把ParticlesProvider+Particles组件、引擎初始化函数以及particles.json配置迁移到新的 Vite 工程结构中——这三部分逻辑与框架无关，配置可以原样复用。

七、小结

cra-template-particles把「创建 React 应用 + 集成 tsParticles」压缩为一条命令：npx create-react-app my-app --template particles。模板通过 template.json 预置@tsparticles/react、@tsparticles/engine与tsparticles依赖，通过 particles.json 提供一份带点击 push、悬停 repulse、粒子连线与碰撞的完整默认配置，再配合<ParticlesProvider init={...}>的一次性引擎初始化机制，让开发者拿到项目即可运行、改 JSON 即可换效果。理解本文的配置逐项释义与源码调用链后，无论是继续在 CRA 中深度定制，还是迁移到基于 Vite 的新脚手架，都能做到心中有数。

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