# @hyperframes/shader-transitions 中文文档

规范地址：https://npmcn.com/package/%40hyperframes/shader-transitions/

版本：0\.8\.226
npm 元数据更新时间：2026-11-01T06:32:48.155Z
中文译文更新时间：2026-11-01T11:00:27.670Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：798 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-14T05:00:25.001Z
- 最新版本发布：2026-11-01T06:32:47.818Z
- 已发布版本数：552（近 12 个月 552 个）

## 中文简介

超帧合成的WebGL着色器转换

## 安装

```sh
npm install @hyperframes/shader-transitions
```

也可以使用：`pnpm add @hyperframes/shader-transitions`、`yarn add @hyperframes/shader-transitions`、`bun add @hyperframes/shader-transitions`

## README

# @hyperframes / shader-transitions

超帧合成的WebGL着色器转换。使用片段着色器渲染gpu加速的场景到场景转换，由GSAP时间轴驱动。

## 安装

```bash
npm install @hyperframes/shader-transitions
```

或者直接通过CDN加载：

```html
<script src="https://cdn.jsdelivr.net/npm/@hyperframes/shader-transitions/dist/index.global.js"></script>
```

## 使用

```typescript
import { init } from "@hyperframes/shader-transitions";

const tl = init({
  bgColor: "#0a0a0a",
  accentColor: "#ff6b2b",
  scenes: ["scene-1", "scene-2", "scene-3"],
  transitions: [
    { time: 3, shader: "domain-warp", duration: 0.8 },
    { time: 8, shader: "light-leak", duration: 0.7 },
  ],
});
```

这个 `init()` 函数为每个过渡预捕获动画场景样本，在播放期间使用所选着色器合成缓存样本，并返回GSAP时间轴。场景动画在播放循环中不运行DOM捕获而通过着色器转换保持前进。如果WebGL不可用，它会回到正常的时间线播放，而不需要着色器合成。

当浏览器公开Chrome的实验性CanvasDrawElement API时，场景 capture使用原生的HTML-in-canvas via `drawElementImage()`。其他浏览器 使用现有的 `html2canvas` 回退。您可以对本机路径进行特性检测 与 `isHtmlInCanvasCaptureSupported()`.

### 使用现有的时间轴

将你自己的GSAP时间轴传递到图层过渡上：

```typescript
const tl = gsap.timeline({ paused: true });
// ... add your scene animations ...

init({
  bgColor: "#000",
  scenes: ["intro", "demo", "outro"],
  transitions: [
    { time: 5, shader: "cinematic-zoom" },
    { time: 12, shader: "glitch", duration: 0.5 },
  ],
  timeline: tl,
});
```

## 可用着色器

| 着色器 | 描述 |
| --- | --- |
| `domain-warp` | 有机噪声为基础的经纱发光边缘 |
| `ridged-burn` | 脊状的噪音燃烧着火花和热光 |
| `whip-pan` | 水平运动模糊模拟快速相机平移 |
| `sdf-iris` | 圆形虹膜擦拭，发光环边 |
| `ripple-waves` | 从中心辐射的同心纹波畸变 |
| `gravitational-lens` | 扭曲重力与色差 |
| `cinematic-zoom` | 径向变焦模糊与彩色边缘 |
| `chromatic-split` | RGB通道分离从中心扩展 |
| `glitch` | 块位移和扫描线的数字故障 |
| `swirl-vortex` | 螺旋旋转与噪声为基础的翘曲 |
| `thermal-distortion` | 热气从底部微微升起 |
| `flash-through-white` | 闪光到白色，然后显示下一个场景 |
| `cross-warp-morph` | 噪声驱动的变形混合两个场景 |
| `light-leak` | 温暖的电影光泄漏与镜头光晕 |

## API

### `init(config): GsapTimeline`

| 选项 | 类型 | 要求 | 描述 |
| --- | --- | --- | --- |
| `bgColor` | `string` | 是 | 场景捕捉的后退背景色（十六进制）。使用构图的主体/画布背景-单独的场景设置自己的 `background-color` 通过CSS。 |
| `accentColor` | `string` | 否 | 着色器发光效果的强调色（十六进制） |
| `scenes` | `string[]` | 是 | 每个场景的元素id，按顺序排列 |
| `transitions` | `TransitionConfig[]` | 是 | 转换定义（见下文） |
| `timeline` | `GsapTimeline` | 否 | 要将过渡附加到的现有时间轴 |
| `compositionId` | `string` | 否 | 覆盖 `data-composition-id` 时间线注册 |
| `previewCaptureFps` | `number` | 否 | 浏览器预览预捕获样本每转换秒。默认为 `30`;渲染使用确定性的每帧合成代替。 |

浏览器预览捕获规模和过渡准备加载UI所有权由 `<hyperframes-player>` （`shader-capture-scale`， `shader-loading`)，而不是组合代码。直接的非玩家预览保留了内置的全保真加载回退。

浏览器预览使用从组合ID、场景DOM/样式签名、转换时间、捕获FPS、比例和尺寸派生的键在IndexedDB中存储捕获的转换快照。在刷新时，匹配的快照被重新加载到WebGL纹理中，而不是再次被捕获。运行时场景或样式表编辑仅将相邻的过渡缓存标记为dirty；重新捕获被延迟到播放，以便编辑保持响应。

### `TransitionConfig`

| 选项 | 类型 | 默认的 | 描述 |
| --- | --- | --- | --- |
| `time` | `number` | \- - - - - - | 启动时间（秒） |
| `shader` | `ShaderName` | \- - - - - - | 上面表格中的着色器名称 |
| `duration` | `number` | `0.7` | 转换持续时间（秒） |
| `ease` | `string` | `"power2.inOut"` | GSAP缓和功能 |

### `SHADER_NAMES`

所有可用的着色器名称字符串的数组，用于验证或构建ui。

```typescript
import { SHADER_NAMES } from "@hyperframes/shader-transitions";
// ["domain-warp", "ridged-burn", "whip-pan", ...]
```

## 分布

| 格式 | 文件 | 用例 |
| --- | --- | --- |
| ESM | `dist/index.js` | 捆绑器（Vite， webpack等） |
| cj | `dist/index.cjs` | Node.js / require（） |
| IIFE | `dist/index.global.js` | `<script>` 标签，CDN（全局） `HyperShader`） |

所有格式都包含源映射。包括TypeScript定义。

## 相关的包

-   [`@hyperframes/core`](https://npmcn.com/package/%40hyperframes/core) ——类型、解析器、运行时
-   [`@hyperframes/engine`](https://npmcn.com/package/%40hyperframes/engine) ——渲染引擎
-   [`hyperframes`](https://npmcn.com/package/%40hyperframes/cli) ——CLI

## 许可证

麻省理工学院

## 常见问题

### @hyperframes/shader-transitions 是什么？

超帧合成的WebGL着色器转换

### 如何安装 @hyperframes/shader-transitions？

在项目目录运行 npm install @hyperframes/shader-transitions，或使用 pnpm add / yarn add / bun add。

### @hyperframes/shader-transitions 支持 TypeScript 吗？

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

### @hyperframes/shader-transitions 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hyperframes/shader-transitions 可以商用吗？

@hyperframes/shader-transitions 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @hyperframes/shader-transitions 还在维护吗？

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