# @basnijholt/particular-drift 中文文档

规范地址：https://npmcn.com/package/%40basnijholt/particular-drift/

版本：0\.2\.0
npm 元数据更新时间：2026-10-07T03:01:23.325Z
中文译文更新时间：2026-11-07T18:04:20.170Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basnijholt/particular-drift
原文对照：https://npmcn.com/package/%40basnijholt/particular-drift/?lang=original
项目主页：https://github.com/basnijholt/particular-drift#readme
源码仓库：https://github.com/basnijholt/particular-drift

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：47.5 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18
- 首次发布：2026-05-12T20:33:19.193Z
- 最新版本发布：2026-10-07T03:01:22.892Z
- 近 30 天下载量：6076（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于基于图像的动画的可再用WebGL粒子漂移渲染器.

## 安装

```sh
npm install @basnijholt/particular-drift
```

也可以使用：`pnpm add @basnijholt/particular-drift`、`yarn add @basnijholt/particular-drift`、`bun add @basnijholt/particular-drift`

## README

# 特别漂流

可再用WebGL2粒子漂移渲染器将固定图像转换为流出粒子动画.

**原始项目 :** [相机/专用驱动器](https://github.com/collidingScopes/particular-drift) 以 [碰撞范围](https://collidingscopes.github.io/)。 。 。 .

此分叉被包装为可嵌入的库. 它有意去掉了原来的演示UI,上传控件,和MP4导出堆栈,因此应用程序可以硬编码自己的图像并拥有周围的界面.

## 安装

```bash
bun add github:basnijholt/particular-drift
```

发布到 npm后, 安装 :

```bash
bun add @basnijholt/particular-drift
```

## 香草用法

```ts
import { createParticularDrift } from '@basnijholt/particular-drift';

const canvas = document.querySelector<HTMLCanvasElement>('#background');

if (canvas) {
  const drift = await createParticularDrift(canvas, {
    imageUrl: '/res/branding/mindroom-logo.png',
    backgroundColor: '#0f0d2e',
    particleColor: '#dda290',
    particleCount: 120000,
    cursorMode: 'repel',
  });

  window.addEventListener('resize', drift.resize);
}
```

## 反应用法

```tsx
import { ParticularDriftCanvas } from '@basnijholt/particular-drift/react';

export function AuthBackground() {
  return (
    <ParticularDriftCanvas
      imageUrl="/res/branding/mindroom-logo.png"
      options={{
        backgroundColor: '#0f0d2e',
        particleColor: '#dda290',
        particleCount: 120000,
      }}
    />
  );
}
```

## API 密码

`createParticularDrift(canvas, options)` 返回 :

-   `loadImage(image)` 装入已有的 `TexImageSource`。 。 。 .
-   `loadImageUrl(url)` 要装入图像 URL.
-   `resize()` 以将后置帆布大小调整到已渲染的 CSS 大小 .
-   `start()` 财务报告和审定财务报表 `stop()` 控制动画.
-   `destroy()` 以取消动画并发布 WebGL 资源.

主要选项:

-   `imageUrl`
-   `imageFit`数字 : `'contain'` 保留画布内的图像宽比; `'stretch'` 使用原始的全扫描图.
-   `particleCount`
-   `particleSpeed`
-   `attractionStrength`
-   `particleOpacity`
-   `particleSize`
-   `edgeThreshold`
-   `edgeSearchSteps`数字 : `1`, (中文(简体) ), `2`,或 `3`;控制粒子搜索附近边缘时使用的有界网状半径.
-   `flowFieldScale`
-   `searchRadius`
-   `noiseType`数字 : `'2D'` 或者说 `'3D'`
-   `interactive`: 当 `true`。 。 。 .
-   `cursorMode`数字 : `'repel'` 将粒子从光标上推开; `'attract'` 把他们拉过来.
-   `cursorRadius`:普通光标影响半径.
-   `cursorStrength`:光标增强战斗力.
-   `cursorReturnStrength`强力将被扰动的粒子拉回 其存储的图像目标.
-   `cursorReturnDamping`: 微粒在光标被扰动后平息时应用了起坝.
-   `backgroundColor`
-   `particleColor`
-   `autoStart`
-   `maxDevicePixelRatio`: 画布分辨率为正封顶; 以下 1 使 CSS 分辨率低于浏览器缩放的 CSS 分辨率( 软件WebGL 上的便宜) 。 粒子大小在画布像素中, 所以较低 `particleSize`编号 :`particleOpacity` 保持同样的表情.
-   `maxFramesPerSecond`: 上限帧率( 默认) `Infinity`;除正数外,任何事物都意味着未被封住)。 模拟在经过一段时间后取得进展,因此不会放慢速度;较低的帧率不太平滑,结算略有不同.

## 发展

```bash
bun install
bun run dev
bun test
bun run typecheck
bun run build
```

## 实例网站

实例网站建自 `index.html` 财务报告和审定财务报表 `demo/main.ts`数字 :

```bash
bun run build:pages
bun run preview:pages
```

GitHub Pages 部署来自 `Pages` 工作流程 `main`在寄存器设置中,将 Pages 源代码设置为 **GitHub 动作**。 。 。 .

实例一旦启用,可在以下网站获取:

```text
https://basnijholt.github.io/particular-drift/
```

## 出版

当一个 GitHub 发布时, 或当 KitHub 发布时, CI 从 GitHub 动作发布到 npm `Publish` 工作流程由人工操作.

为此软件包配置 npm 信任出版 :

-   提供者: GitHub 动作
-   拥有者 : `basnijholt`
-   仓库 : `particular-drift`
-   工作流程文件名 : `publish.yml`

然后用铸币标记放出. 工作流程剥离领先 `v`时,更新 `package.json` 中,并将该版本发布到 npm:

```bash
gh release create v0.1.1 --generate-notes
```

## 浏览器要求

-   网络GL2
-   Canvas 图像加载在使用远程图像 URL 时必须满足浏览器 CORS 规则.

## 许可证

麻省理工学院. 见 [LICENSE.txt (英语)](https://npmcn.com/package/%40basnijholt/particular-drift/LICENSE.txt)。 。 。 .

## 原作者

特别的漂流是由Colliding Species创建的. 这个软件包是一个以图书馆为主的叉子.

-   原始仓库 : [github.com/缩写缩写缩写](https://github.com/collidingScopes/particular-drift)
-   原始现场演示 : [(原始内容存档于2018-09-26) (英语). Scopes.github.io/particul-drift](https://collidingscopes.github.io/particular-drift)
-   原作者网站 : [(原始内容存档于2013-10-12). Scops.github.io](https://collidingscopes.github.io/)
-   支持原作者 : [给我买杯咖啡](https://www.buymeacoffee.com/stereoDrift)

[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/stereoDrift)

## 常见问题

### @basnijholt/particular-drift 是什么？

用于基于图像的动画的可再用WebGL粒子漂移渲染器\.

### 如何安装 @basnijholt/particular-drift？

在项目目录运行 npm install @basnijholt/particular-drift，或使用 pnpm add / yarn add / bun add。

### @basnijholt/particular-drift 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basnijholt/particular-drift 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basnijholt/particular-drift 可以商用吗？

@basnijholt/particular-drift 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @basnijholt/particular-drift 的下载量有多少？

根据 npm 官方下载统计，@basnijholt/particular-drift 在 2026/10/08 – 2026/11/06 这 30 天内被下载 6,076 次，日均约 203 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @basnijholt/particular-drift 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/07（1 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。