particles.js 在线调试器 — 实时配置编辑与生成

用控件或原始 JSON 编辑 particles.js 配置，实时查看运行效果，并复制 JSON 或可直接粘贴的 HTML 代码片段。

发现问题，或者觉得哪里可以更好？每条消息我们都会阅读，并尽快修复。

这个 particles.js 在线调试器是 particles.js 配置的实时编辑器和生成器。用控件修改粒子数量、颜色和形状、连线、运动以及悬停和点击效果，或直接编辑完整的 JSON 配置，预览会随输入重新运行。两种视图编辑的是同一份配置，所以你可以先用滑块粗调，再在 JSON 中细调。效果满意后，复制 JSON，或复制带 script 标签和 particlesJS() 调用的完整 HTML 代码片段。

预览运行的是真正的 particles.js 2.0.0 库，而不是仿制品，所见即你的页面将呈现的效果，包括它的各种特性：只接受十六进制颜色，开启密度时粒子数量会随画布大小缩放，连线的开销增长得很快。FPS 读数可以帮你在把配置部署到手机之前做出判断。particles.js 本身自 2015 年的 2.0.0 版之后就没有更新过；它在当前浏览器中仍能正常运行，下方说明解释了什么时候选择它仍在维护的继任者 tsParticles 更好。

使用方法

选择一个预设作为起点，或把你自己的配置粘贴到 JSON 编辑器中（particlesjs-config.json、particlesJS("particles-js", {...}) 调用或普通对象都可以）。也可以把 .json 文件拖到工具上。
在“控件”标签页中调整配置：粒子数量和密度、颜色、形状、透明度、大小、连线、运动和交互。也可以直接编辑 JSON；错误会显示在编辑器下方，预览保留最后一份有效的配置。
设置预览背景色或背景图以匹配你的页面，在预览上悬停和点击以测试交互效果。用“放大”或“全屏”查看完整尺寸的效果，并留意 FPS 读数。
选择输出方式：HTML 片段、particlesJS.load 写法、React 组件或 JSON 配置。再选择容器是全页背景还是填满父元素。
复制或下载，然后把 HTML 片段粘贴到页面结束标签 </body> 之前。

常见问题

如何把 particles.js 添加到我的网站？

添加一个带 id 的空元素，例如 <div id="particles-js"></div>，用 CSS 给它设置尺寸，用 script 标签加载库（jsDelivr 上的地址是 cdn.jsdelivr.net/npm/ 后接 particles.js@2.0.0/particles.min.js），然后用这个 id 和你的配置调用 particlesJS("particles-js", { ...config })。脚本必须在元素存在之后运行，所以把它放在 </body> 之前。结果一片空白最常见的原因是容器没有高度：particles.js 根据元素大小设置画布，高度为 0 的 div 得到的画布高度也是 0。本工具生成的 HTML 片段包含了全页背景或填满父元素所需的 CSS。

如何在 React 或 Next.js 中使用 particles.js？

用 npm install particles.js 安装，然后在 useEffect 中导入，使它只在浏览器中运行（它会用到 window，所以在顶层导入会破坏 Next.js 的服务端渲染）。元素渲染完成后调用 window.particlesJS("particles-js", config)，并在组件卸载时清理：对 window.pJSDom 中的每一项调用 pJS.fn.vendors.destroypJS()，并把 window.pJSDom 重置为空数组，否则动画循环会继续运行，下次挂载也会失败。这里的 React / Next.js 输出就是一个做了这些处理的组件。对于新的 React 项目，仍在维护的 @tsparticles/react 包更为合适。

particles.js 还在维护吗？particles.js 与 tsParticles 对比

没有。Vincent Garreau 开发的 particles.js 停留在 2015 年发布的 2.0.0 版，此后其仓库再没有发布过新版本。由于它只用到 canvas 和 requestAnimationFrame，在当前浏览器中仍能运行，很多网站也在使用。Matteo Bruni 开发的 tsParticles 最初是它的 TypeScript 移植版，现在是其积极维护的继任者：形状和效果更多，有官方的 React、Vue、Angular 和 Svelte 组件，性能选项更好，还能读取 particles.js 的大部分选项。在静态页面上快速做一个无依赖的背景，用 particles.js；框架应用或需要维护多年的项目，选 tsParticles。

particles.js 会拖慢网站在手机上的速度吗？

可能会。每一帧都要重绘每个粒子，开启连线后每个粒子还要和其他所有粒子计算距离，所以开销随粒子数量的平方增长。retina_detect 会让高 DPI 手机上绘制的像素翻两到三倍。保持流畅的方法：保持开启密度，让小屏幕上的粒子更少；开启连线时粒子保持在约 100 个以内；FPS 下降时关闭连线或 retina_detect；访客设置了 prefers-reduced-motion 时不初始化 particles.js。浏览器会在后台标签页中暂停 requestAnimationFrame，所以标签页隐藏时没有任何开销。

为什么我的 particles.js 背景不显示？

按顺序检查以下几点：容器有实际高度（height: 100% 只有在父元素也有高度时才有效，所以代码片段使用 position: fixed 或 absolute）；particlesJS 调用在元素存在之后运行；粒子颜色与背景色不同；其他内容没有用不透明背景把它挡住；浏览器控制台没有报错。使用 particlesJS.load 时，页面必须通过 http(s) 提供，因为从 file:// 加载 JSON 文件会被阻止。颜色写成名称或 rgb() 而不是十六进制，也会让 particles.js 停止绘制；本工具会标出这种情况。

particles.js 可以使用图片或自定义形状吗？

可以。把 shape.type 设为 "image"，shape.image.src 设为图片 URL；width 和 height 设定其宽高比，size 选项设定绘制大小。PNG、JPG、GIF 和 WebP 作为普通图片加载。SVG 文件通过 XMLHttpRequest 下载以便替换颜色，这意味着托管 SVG 的服务器必须允许跨域请求。除图片外，内置形状有 circle、edge（正方形）、triangle、polygon 和 star，polygon.nb_sides 设定多边形的边数或星形的角数。传入一个形状数组，每个粒子会随机取其中一种。

particles.js 配置参考：重要的选项

particles.js 配置有三个顶层键：particles（绘制什么、如何运动）、interactivity（如何响应鼠标）和 retina_detect。省略的键会回退到库的默认值，而这些默认值很“重”：400 个半径为 20 的粒子，并开启连线。所以只设置了颜色的配置，看起来并不像演示效果。

• particles.number.value 和 density：开启 density.enable 时，value 是 value_area × 1000 平方像素面积内的粒子数，实际数量随画布缩放。value_area 为 800 时设 80 个粒子，在 1920×1080 屏幕上约为 200 个，在手机上只有几十个。

• particles.color.value：十六进制字符串、十六进制字符串数组（每个粒子取其一）、"random" 或 {r, g, b} 对象。不支持颜色名称和 rgb() 字符串，使用它们会让动画停止。

• particles.shape.type：circle、edge、triangle、polygon、star 或 image，也可以是它们组成的数组。stroke 添加描边；polygon.nb_sides 设定多边形的边数和星形的角数。

• opacity 和 size：value 是最大值，random 会为每个粒子在 0 到最大值之间随机取值，anim 让它按给定速度在 opacity_min / size_min 和 value 之间脉动。

• line_linked：在距离小于 distance 像素的粒子之间画线，距离越远线越淡。它的 color 必须是单个十六进制值。

• move：speed、direction（none 或八个方向之一）、random（速度各异）、straight（不漂移）、out_mode（out 从另一侧绕回，bounce 在边缘反弹）、bounce（粒子之间相互碰撞）和 attract。

• interactivity.events：onhover 模式有 grab（向光标画线）、bubble（靠近时变大或变淡）和 repulse（推开）；onclick 模式有 push（添加粒子）、remove、bubble 和 repulse。它们的强度在 interactivity.modes 中设置。detect_on 默认为 canvas；设为 window 时，即使内容盖住了画布也会响应，使用的是视口坐标。

安装 particles.js：CDN、npm 或自行托管

通过 CDN：使用一个 script 标签，其 src 为 cdn.jsdelivr.net/npm/ 后接 particles.js@2.0.0/particles.min.js（上面的 HTML 片段包含完整标签）。像这样固定版本，而不要使用 @latest。npm 包里只有未压缩的 particles.js；.min.js 文件（约 23 KB）由 jsDelivr 按请求生成，也正因为它是生成的，jsDelivr 建议不要为它添加 SRI 完整性哈希。

通过 npm：npm install particles.js@2.0.0，然后在客户端代码中 import "particles.js"。这个包不导出任何内容；导入它会定义 window.particlesJS 和 window.pJSDom。它不带 TypeScript 类型，所以 TypeScript 项目需要加一行 declare module "particles.js"，并通过 window 调用。

自行托管：从 npm 包中复制 particles.js（或从 jsDelivr 获取压缩版文件）到你的静态文件中，并让 script 标签指向它。该库不使用 eval，所以在允许你自己脚本的严格 Content-Security-Policy 下也能运行；图片形状需要在 img-src 中允许其主机，SVG 图片或 particlesJS.load 还需要在 connect-src 中允许该主机。

particles.js 采用 MIT 许可证，所以只要在文件中保留许可声明，就可以用于商业项目。

让粒子背景既快速又无障碍

动态背景只是装饰，绝不应该碍事。尊重减少动态效果的设置，只在访客没有要求减少动态效果时才启动它：if (!matchMedia("(prefers-reduced-motion: reduce)").matches) particlesJS("particles-js", config)。也可以保留背景但把 move.enable 设为 false，这样只绘制一帧静止画面。

保持文字可读：检查文字颜色与背景色以及粒子和连线颜色的对比度，必要时在文字下方加一层半透明遮罩。用 position: relative 和更高的 z-index 把内容放在画布上方；如果画布不能拦截点击，给它设置 pointer-events: none，并用 detect_on: "window" 实现悬停效果。

在真机上测试。这个调试器中的 FPS 读数衡量的是你的电脑，而中端手机可能只有其三分之一。按帮助大小排序，最有效的调整依次是：减少粒子数量、增大 value_area、关闭 retina_detect、禁用连线。