企业官网建设流程全解析

tsParticles Line Shape 粒子形状使用指南：安装加载、Option 映射与源码原理

【免费下载链接】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 的 Line Shape 是一个将粒子渲染为细线（thin line）或轨迹形状的官方形状扩展包，适合制作网格、光束、雨丝、连线等粒子视觉效果。本文将围绕 shapes/line/README.md 展开，完整讲解该形状的安装方式、加载顺序、Option 映射规则与常见坑，并结合仓库源码剖析其底层绘制原理，帮助你快速把particles.shape.type: "line"接入自己的项目。

快速检查清单（Quick checklist）

在使用 Line Shape 之前，请按顺序确认以下三步：

1. 安装@tsparticles/engine（或使用下方 CDN 打包文件）；
2. 在调用tsParticles.load(...)之前调用包提供的加载函数loadLineShape(...)；
3. 在tsParticles.load(...)的配置中启用 Line Shape 对应的选项。

第 2 步尤其关键：加载函数必须在load之前执行，否则引擎在解析配置时会因为找不到名为line的已注册形状而报错（详见下文「常见坑」）。

如何安装与加载

CDN / Vanilla JS / jQuery

在纯浏览器（Vanilla JS）或 jQuery 场景下，引入 CDN 版本即可使用。Vanilla 配置需要一个必备文件：tsparticles.shape.line.min.js。

引入该文件后，会把加载函数loadLineShape暴露到全局作用域，随后在页面脚本中调用：

(async () => { await loadLineShape(tsParticles); await tsParticles.load({ id: "tsparticles", options: { /* options */ /* here you can use particles.shape.type: "line" */ }, }); })();

从源码看，CDN 全局挂载是由 browser.ts 完成的：它读取全局对象globalThis，将loadLineShape写入全局，同时把包内容重新导出：

const globalObject = globalThis as typeof globalThis & { __tsParticlesInternals?: Record<string, unknown>; loadLineShape?: typeof loadLineShape; }; globalObject.__tsParticlesInternals = globalObject.__tsParticlesInternals ?? {}; globalObject.loadLineShape = loadLineShape; export * from "./index.js";

因此浏览器脚本中可以直接使用loadLineShape这个全局函数，无需手动 import。

ESM / CommonJS

该包同时兼容 ES Module 与 CommonJS。首先安装依赖：

$ npm install @tsparticles/shape-line

或使用 yarn：

$ yarn add @tsparticles/shape-line

然后在应用中导入。CommonJS 用法（require）：

const { tsParticles } = require("@tsparticles/engine"); const { loadLineShape } = require("@tsparticles/shape-line"); (async () => { await loadLineShape(tsParticles); })();

ESM 用法（import）：

import { tsParticles } from "@tsparticles/engine"; import { loadLineShape } from "@tsparticles/shape-line"; (async () => { await loadLineShape(tsParticles); })();

从 package.json 的exports字段可以看到，该包提供了完整的模块入口映射：import指向dist/esm/index.js、require指向dist/cjs/index.js、浏览器构建指向dist/browser/index.js，类型声明位于dist/types/index.d.ts，并且包声明了"type": "module"，因此上述两种模块体系都能正常解析。

懒加载入口（@tsparticles/shape-line/lazy）

如果你希望把形状代码拆分成按需加载的 chunk，可以使用懒加载子路径@tsparticles/shape-line/lazy（对应 index.lazy.ts）：

import { tsParticles } from "@tsparticles/engine/lazy"; import { loadLineShape } from "@tsparticles/shape-line/lazy"; (async () => { await loadLineShape(tsParticles); })();

懒加载版本在注册插件时才通过await import("./LineDrawer.js")动态引入绘制器实现，从而缩小首屏包体。两种入口最终都会通过engine.pluginManager.addShape(["line"], ...)注册名为line的形状。

Option 映射（Option mapping）

Line Shape 的配置项映射如下：

• 主选项键（Primary options key）：particles.shape.type: "line"
• 形状专属选项键（Shape-specific options key）：particles.shape.options.line

配置示例（JSON）：

{ "particles": { "shape": { "type": "line", "options": { "line": {} } } } }

其中options.line对象支持一个可选属性cap，用于控制线条端点的样式，取自 Canvas 的lineCap属性：

该参数由 Utils.ts 中的绘制函数读取并应用：

interface ILineData { cap?: CanvasLineCap; } export function drawLine(data: IShapeDrawData): void { const { context, particle, radius } = data, shapeData = particle.shapeData as ILineData | undefined, centerY = 0; context.moveTo(-radius, centerY); context.lineTo(radius, centerY); context.lineCap = shapeData?.cap ?? "butt"; }

注意particle.shapeData可能为undefined，因此源码使用空值合并?? "butt"保证始终有兜底值。想要更有“光束感”的圆头线条，可以这样配置：

{ "particles": { "shape": { "type": "line", "options": { "line": { "cap": "round" } } } } }

线条长度与方向由谁决定

从 LineDrawer.ts 和drawLine的实现可以看出，Line Shape 的绘制不依赖额外的复杂几何计算：

• 线的长度由粒子的半径（radius，即particles.size相关配置）决定：绘制范围是从(-radius, 0)到(radius, 0)的一条水平线段，总长度为2 * radius；
• 线始终先以水平方向绘制，其最终旋转角度由粒子自身的旋转（rotate）等运动系统决定；
• LineDrawer.ts 中的getSidesCount()返回1，表示该形状按一条边处理，这会影响碰撞计算等依赖“边数”的引擎逻辑。

因此，要让 line 粒子呈现倾斜、扫掠的效果，通常需要配合粒子的旋转与移动选项一起配置。

常见坑（Common pitfalls）

1. 在loadLineShape(...)之前调用tsParticles.load(...)

这是最常见的错误。引擎在解析配置时，若particles.shape.type指定的形状尚未注册，会直接跳过或报错。务必保证加载顺序为：

await loadLineShape(tsParticles); // 先注册 await tsParticles.load({ ... }); // 后加载配置

2. 启用高级选项前先核对 peer 依赖

该包将@tsparticles/engine声明为 peerDependency（见 package.json），loadLineShape内部还会调用engine.checkVersion(__VERSION__)校验引擎版本兼容性（见 index.ts）。如果你在options.line.cap等高级配置上遇到异常，先检查@tsparticles/engine是否安装、版本是否与@tsparticles/shape-line匹配。

3. 一次只修改一组选项

Line Shape 与移动（move）、旋转（rotate）、大小（size）等模块联动紧密。排查视觉效果问题时，建议一次只改动一个选项组（例如只改cap、只改size），以便快速定位回归来源。

源码级原理：一个形状是如何被注册和绘制的

把整个调用链串起来看，Line Shape 的工作流程如下：

1. 注册：index.ts 中的loadLineShape(engine)先做版本校验，然后调用engine.pluginManager.addShape(["line"], () => Promise.resolve(new LineDrawer()))，把"line"这个名字与LineDrawer工厂函数关联起来；
2. 绘制：引擎绘制粒子时，会从形状数据中取出context、particle、radius等参数组成IShapeDrawData（见引擎的 IShapeDrawData.ts，其中包含 canvas context、帧间隔delta、粒子实例等），交给LineDrawer.draw(data)；
3. 落笔：draw(data)转调drawLine(data)，在上下文中执行moveTo(-radius, 0)与lineTo(radius, 0)，并按shapeData.cap设置端点样式，完成一条水平线的绘制。

这一机制与引擎内其他形状（circle、square、star 等）完全一致——都是实现IShapeDrawer接口、以工厂函数注册到插件管理器。仓库内的 utils/configs 目录中收录了大量可直接运行的真实配置示例，可作为编写 line 形状粒子配置的参考。

总结

Line Shape 是一个轻量但实用的粒子形状：一行源码画出一条线段，配合粒子的大小、旋转与移动即可衍生出雨丝、光束、网格等多种视觉效果。使用时的要点可归结为三句话：先安装@tsparticles/engine，在tsParticles.load之前调用loadLineShape，在particles.shape.options.line中按需配置cap端点样式。更多官方包目录与主文档可继续查阅仓库根目录的 README.md 与 CHANGELOG.md。

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