tsParticles 从 2.x 升级到 3.x 的配置迁移指南

核心变更点解析

在 tsParticles 3.x 版本中，开发团队对 API 进行了重大重构，其中最重要的变化包括：

1. 连线属性重命名
   原先的 line_linked 配置项已更名为更语义化的 links，这是最直观的修改点。例如：

   // 旧版 (2.x)
   line_linked: { enable: true }
   
   // 新版 (3.x)
   links: { enable: true }
   

2. 初始化方式重构
   3.x 版本引入了更模块化的加载机制，必须显式加载核心引擎和功能插件：

   // 必须首先加载核心引擎
   await tsParticles.load("tsparticles", {
     // 配置项...
   });
   

典型升级问题解决方案

空白渲染问题

当从 2.8.0 直接替换为 3.x 版本时，常见空白页面问题通常由以下原因导致：

1. 未正确加载引擎包
   3.x 版本需要明确指定使用的功能包，例如完整包需这样引入：

   <script src="tsparticles.engine.min.js"></script>
   <script src="tsparticles.slim.min.js"></script>
   

2. 异步加载未处理
   新版 load 方法返回 Promise，建议使用 async/await：

   async function initParticles() {
     await tsParticles.load("tsparticles", config);
   }
   initParticles();
   

配置迁移完整示例

以下是完整的 2.x 到 3.x 配置转换示例：

// 2.x 版本配置
particles: {
  size: { value: 1 },
  line_linked: { enable: true },
  move: { enable: true, speed: 1.5 }
}

// 3.x 等效配置
const config = {
  particles: {
    size: { value: 1 },
    links: { enable: true },  // 关键修改点
    move: { enable: true, speed: 1.5 }
  }
};

// 必须使用新的加载方式
tsParticles.load("tsparticles", config).then(container => {
  console.log("初始化完成");
});

升级建议

1. 版本选择
   建议直接使用最新稳定版而非中间的 3.3.0，以获得完整功能和修复。

2. 按需加载
   3.x 支持功能模块化，可根据实际需求选择加载：

   • 基础包：仅包含核心引擎
   • 完整包：包含所有交互效果
   • 扩展包：特定场景插件

3. 错误排查
   如遇初始化问题，建议检查：

   • 控制台是否有加载错误
   • 配置项是否使用新版命名规范
   • 是否正确处理了异步加载

通过以上调整，开发者可以充分利用 3.x 版本改进的性能和新特性，如更精细的动画控制和更好的移动端支持。