# @flare-engine/render-web 中文文档

规范地址：https://npmcn.com/package/%40flare-engine/render-web/

版本：0\.4\.12
npm 元数据更新时间：2026-11-12T19:45:59.507Z
中文译文更新时间：2026-11-15T23:39:49.389Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：162 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：canvaskit-wasm \>=0\.40\.0
- 首次发布：2026-07-01T12:28:06.334Z
- 最新版本发布：2026-11-12T19:45:58.877Z
- 近 30 天下载量：1995（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

@flare- engine/ landers fram- landers 的 CanvasKit 备份网络渲染器

## 安装

```sh
npm install @flare-engine/render-web
```

也可以使用：`pnpm add @flare-engine/render-web`、`yarn add @flare-engine/render-web`、`bun add @flare-engine/render-web`

## README

# @flare-engine/render-web (英语)

Canvas Kit 备份的网络渲染器 `@flare-engine/render`. 提供WebGL地表,被接通到CanvasKit原始物的帧-后置模块,以及带有完整的乒乓荫道管的后处理地表.

## 安装

```sh
bun add @flare-engine/render-web canvaskit-wasm
```

`canvaskit-wasm` 是一个可选的同伴依赖性——只在网络环境中需要.

## 入境点

### `loadCanvasKit` —— 说 `loader.ts`

装入 CanvasKit WASM 二进制并返回已准备好 `CanvasKit` 举个例子 将 URL/路径到 `canvaskit.wasm` 二进制( 需要), 可选 `onProgress(fraction)` 下载回调和可选 `LoadCanvasKitOptions` (单位:千美元)`stallMs`,默认为15000; `deadlineMs`,默认的4500 绑定负载.

```ts
import { loadCanvasKit } from '@flare-engine/render-web';

const kit = await loadCanvasKit('/canvaskit.wasm', undefined, { stallMs: 10_000, deadlineMs: 30_000 });
```

一个成功的负载被缓存——后来调回同样的例子. A 类 **失败** 负载没有被缓存: 稍后的呼叫重试从头开始,而不是被困在更早的拒绝上.

### `createWebSurface` —— 说 `web-surface.ts`

创建基于 WebGL 的 WebGL `CanvasKit` 表面从一个 `HTMLCanvasElement` 返回 a `WebSurface` 控件 : `canvas` 联合国 `CanvasLike` 页:1 `Renderer.setCanvas()`, (中文(简体) ), `ckCanvas` (屏幕上画布和CanvasKit一样) `Canvas`,用于 `drawPicture`, (中文(简体) ), `flush()` 财务报告和审定财务报表 `dispose()`。直到 `flush()`. 回归 `null` 当 WebGL 不可用时.

```ts
import type { CanvasKit } from 'canvaskit-wasm';
import { createWebSurface } from '@flare-engine/render-web';

declare const kit: CanvasKit;
declare const canvasEl: HTMLCanvasElement;

const web = createWebSurface(kit, canvasEl);
if (!web) throw new Error('WebGL unavailable');

// ...draw through web.canvas / web.ckCanvas each frame...
web.flush();    // present

// Teardown:
web.dispose();
```

### `createWebSkiaModule` —— 说 `web-skia-module.ts`

适应 a `CanvasKit` 实例 `FrameRendererModule` 接口 `@flare-engine/render`是因为 `createFrameRenderer`组合 `PictureRecorder`, (中文(简体) ), `Paint`, (中文(简体) ), `RSXform`, (中文(简体) ), `XYWHRect`和荫道的助手.

```ts
import type { CanvasKit } from 'canvaskit-wasm';
import type { SkImageLike } from '@flare-engine/assets';
import type { SpriteDrawCommand } from '@flare-engine/render';
import { createWebSkiaModule, createWebSurface } from '@flare-engine/render-web';
import { createFrameRenderer } from '@flare-engine/render';

declare const kit: CanvasKit;
declare const width: number;
declare const height: number;
declare const atlasImage: SkImageLike;
declare const commands: SpriteDrawCommand[];
declare const canvasEl: HTMLCanvasElement;

const mod = createWebSkiaModule(kit);
const renderer = createFrameRenderer(mod);

// Present onto a WebGL-backed CanvasKit surface.
const web = createWebSurface(kit, canvasEl);
if (!web) throw new Error('WebGL unavailable');
const canvas = web.ckCanvas;

renderer.beginFrame(width, height, 0, 1);
renderer.drawAtlas(atlasImage, commands);
const picture = renderer.endFrame();
// endFrame() returns the backend-neutral PictureLike; cast to CanvasKit's Picture to present.
// The caller owns the picture: delete it once drawn, or each frame leaks a WASM-side object.
if (picture) {
  const ckPicture = picture as Parameters<typeof canvas.drawPicture>[0];
  canvas.drawPicture(ckPicture);
  ckPicture.delete();
}
web.flush();
```

### `createPostFxSurface` —— 说 `postfx-surface.ts`

创建一个 `PostFxSurface` 它拥有一个外屏的场景帆布,一个乒乓球中间体,和一个上屏的WebGL表面. 时 `composite()` 它运行呼叫器的时间 `EffectChain` 通过编译的 SKSL 阴影并擦去结果来显示.

```ts
import type { Canvas, CanvasKit } from 'canvaskit-wasm';
import { createPostFxSurface } from '@flare-engine/render-web';
import { EffectChain, createVignette, createBloom } from '@flare-engine/postfx';

declare const kit: CanvasKit;
declare const canvasEl: HTMLCanvasElement;
declare const newW: number;
declare const newH: number;
declare function drawHud(canvas: Canvas): void;

const chain = new EffectChain();
chain.add(createVignette('vig', { intensity: 0.6, radius: 0.8 }));
chain.add(createBloom('bloom', { threshold: 0.5, intensity: 0.9 }));

const surface = createPostFxSurface(kit, canvasEl, chain);
if (!surface) throw new Error('WebGL unavailable');

// Game loop:
surface.clear([0, 0, 0]);
// ...draw to surface.sceneCanvas()...
surface.composite();        // runs the shader chain at chain.globalIntensity, presents to onscreenCanvas()

// Draw crisp overlays AFTER composite() but BEFORE flush(). Null while the context is lost.
const overlay = surface.onscreenCanvas();
if (overlay) drawHud(overlay);

surface.flush();            // present the frame

// On resize:
surface.resize(newW, newH);
surface.clear([0, 0, 0]);

// Teardown:
surface.dispose();
```

通过空的 `new EffectChain()` 用于零头通过(没有阴影编译).

`composite()` 读取 `chain.globalIntensity` ——价值 `EffectChain.setGlobalIntensity`, (中文(简体) ), `PostFxController.setMotionScale` 编辑 `@flare-engine/a11y` 桥面写作——所以从相框到相框的减动尺度. 过 `composite(k)` 仅在您要将新的全球强度写入链条时; 调用 `composite(1)` 每个相框都会在传阅前取消11式设定.

### 背景损失和恢复

`sceneCanvas()` 财务报告和审定财务报表 `onscreenCanvas()` 返回时 `Canvas | null` 两者都是 `null` ,而WebGL 语境丢失. `PostFxSurface` 自愈: 打开 `webglcontextlost` 它自己标记丢失并停止接触GPU对象(`clear`编号 :`fadeTrail`编号 :`composite`编号 :`flush` 成为无操作); 上 `webglcontextrestored` 它重建上下文和表面 在同一画布上,并重新澄清到最后的背景。 票价 `isLost()` 以驱动主机侧倒计时, 等待恢复 :

```ts
import type { PostFxSurface } from '@flare-engine/render-web';

declare const surface: PostFxSurface;
declare function showStaticFallback(): void;

if (surface.isLost()) showStaticFallback();
```

## 结构说明

-   `@flare-engine/postfx` 后端中性; `render-web` 提供 CanvasKit shim (`SkiaPostFxModuleLike`路线 `RuntimeEffect.Make` 给CanvasKit.
-   乒乓圈在热道上是无分配的:在地表创建时,子阵列和矩抓缓冲被预先分配.
-   `buildPass` 被称作每个帧( 没有记忆) 因为 `EffectChain` 没有突变信号; 未来 `buildPassInto` 零空格形式在 `@flare-engine/postfx` 正确的修复.

见 [API 规格](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md) 财务报告和审定财务报表 [结构](https://github.com/grzott/flare-engine/blob/main/docs/design/architecture.md) 给整个输油管.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @flare-engine/render-web 是什么？

@flare- engine/ landers fram- landers 的 CanvasKit 备份网络渲染器

### 如何安装 @flare-engine/render-web？

在项目目录运行 npm install @flare-engine/render-web，或使用 pnpm add / yarn add / bun add。

### @flare-engine/render-web 支持 TypeScript 吗？

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

### @flare-engine/render-web 支持 ESM 还是 CommonJS？

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

### @flare-engine/render-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flare-engine/render-web 可以商用吗？

@flare-engine/render-web 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @flare-engine/render-web 的下载量有多少？

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

### @flare-engine/render-web 还在维护吗？

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

