# @clayzo/webgl-player 中文文档

规范地址：https://npmcn.com/package/%40clayzo/webgl-player/

版本：0\.3\.21
npm 元数据更新时间：2026-11-04T22:22:49.113Z
中文译文更新时间：2026-11-10T00:38:28.895Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40clayzo/webgl-player
原文对照：https://npmcn.com/package/%40clayzo/webgl-player/?lang=original

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

- 包体积（解压后）：1.2 MB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13
- 运行依赖：2 个
- peer 依赖：react \>=18\.3 \<20
- 首次发布：2026-08-25T00:44:50.413Z
- 最新版本发布：2026-11-04T22:22:48.958Z
- 近 30 天下载量：17400（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

轻量级Clayzo动画玩家. WebGL2,没有斯基亚,没有设置.

## 安装

```sh
npm install @clayzo/webgl-player
```

也可以使用：`pnpm add @clayzo/webgl-player`、`yarn add @clayzo/webgl-player`、`bun add @clayzo/webgl-player`

## README

# @clayzo/webgl-玩家

轻量级Clayzo WebGL2播放器. 它嵌入了引擎核心和内置效果,因此回放不需要认证请求,舞台WASM文件,或Clayzo账户.

对于iOS和macOS应用程序,同样的文档通过Swift软件包在本地播放 [克莱佐/克莱佐-摇摆](https://github.com/Clayzo/clayzo-swift)。 。 。 .

```bash
npm install @clayzo/webgl-player
```

```ts
import { createPlayer, checkCoverage } from "@clayzo/webgl-player";

// `loaders` is optional: a bundle's, or your own font and image loaders.
const coverage = await checkCoverage(document, loaders);
if (!coverage.supported) throw new Error(coverage.reasons.join("; "));

const player = await createPlayer({ canvas, document, loaders, interactive: true });
player.play();
```

稳定的公共表面是: `createPlayer()`, (中文(简体) ), `checkCoverage()`, (中文(简体) ), `registerFont()`, (中文(简体) ), `CreatePlayerOptions`,以及 `PlayerHandle`发动机手柄、遮光源、渲染器类、WASM ABI和上下文池内部是故意私密的.

React and Next 客户端可以使用可选客户端的切入点 :

```tsx
import { ClayzoPlayer } from "@clayzo/webgl-player/react";

export function Hero() {
  return (
    <ClayzoPlayer
      document={document}
      poster="/hero.poster.webp"
      posterTick={240}
      label="A cube folding into the logo"
    />
  );
}
```

组件显示 `poster` 一次加载玩家,只当它靠近取景口时,然后淡出 `posterTick` 和游戏. `clayzo package hero.json --poster 240` 写入匹配 `hero.poster.webp`当读者要求减少其动议时 `posterTick`· ; `reducedMotion="pause"` 停止它现在的位置 `"ignore"` 反正还是会玩的. `autoplay={false}` 别动, `decorative` 隐藏在屏幕阅读器中而不是 `label`,以及 `fallback` 如果玩家无法创建,则显示. `document` 可能会是 `null` 并装入.

没有反应的页面可以使用 `<clayzo-player>` 元素,具有相同行为:

```html
<script type="module">import "@clayzo/webgl-player/element";</script>
<clayzo-player src="/hero.clayzo" poster="/hero.poster.webp" label="A cube folding into the logo"></clayzo-player>
```

`src` 是引擎 JSON 文档或 `.clayzo` 捆绑 属性为 `poster`, (中文(简体) ), `poster-tick` (默认到滴答 捆绑的海报 是在), `autoplay`, (中文(简体) ), `loop`, (中文(简体) ), `interactive`, (中文(简体) ), `reduced-motion`, (中文(简体) ), `label` 财务报告和审定财务报表 `decorative`; 设置 `autoplay="false"` 关闭一个。 这个元素有 `play()`, (中文(简体) ), `pause()`, (中文(简体) ), `seek()`, (中文(简体) ), `setInput()` 财务报告和审定财务报表 `fire()`和火灾 `ready` 财务报告和审定财务报表 `error`。如果玩家无法创建,则显示其中的内容.

## 国家

有状态机器的文档一次播放一个状态,如闲置,徘徊,按住,加载和完成等. 指向活动、投入和 `setState` 将其移动到状态之间,玩家在显示每个变化的帧后打回.

```ts
const player = await createPlayer({
  canvas,
  document,
  onStateChange: ({ from, to }) => console.log(from.name, "→", to.name),
});
player.play();
player.setInput("loading", true);
player.setState("done", { instant: true });
player.currentState; // { id, name }
```

`initialState` 从另一个状态开始, `onComplete` 报告一旦达到尾声的状态 `onPointer` 报告帆布上和受打击地区的事件. `setReducedMotion(true)` 在最后一帧显示每个状态,而不是动画,当读者要求减少运动时,组件会这样做. `stateMachine: false` 播放简单的时间表.

## 页面上的许多玩家

玩家分享了GPU上下文,但每个像素仍需要内存,手机会关闭一个使用过多的页面. 玩家在屏幕附近保持由玩家绑定的内存,而不是在页面上有多少人:

-   屏幕外玩家停止绘图( O)`pauseWhenOffscreen`,默认为).
-   玩家不止一个取景口,还可以释放出他们的GPU内存和画布的像素(`releaseWhenOffscreen`,默认为). 画布保持其布局框. 在屏幕的半个取景口内,玩家再次绘制出相同的帧后才能被看到. 钟不跑而去,所以 `tick` 和游戏状态 正是它留下他们.
-   `resolution: "display"` 封顶设备像素比 `maxPixelRatio` (默认) `2`),在3x手机上所持有的像素还不到一半.
-   在玩家移动到新上下文时,丢失的GPU上下文保留了画布上的最后帧. 失败到 `onError` (或 `onPlayerError` 在反应中,没有东西被抛出.

```ts
// A player that must reappear instantly, and a crisper one on 3x screens.
await createPlayer({ canvas, document, releaseWhenOffscreen: false, maxPixelRatio: 3 });
```

当文档资产 URL 无法直接获取时, 提供字体或图像加载器 。 使用一个 `.clayzo` 当您想要将资产与文档打包时, 将进行捆绑 。 选择 `@clayzo/canvaskit-player` 何时 `checkCoverage()` 报告一个不支持的构造或完全的参考委托的忠诚度大于转移大小.

## 常见问题

### @clayzo/webgl-player 是什么？

轻量级Clayzo动画玩家\. WebGL2,没有斯基亚,没有设置\.

### 如何安装 @clayzo/webgl-player？

在项目目录运行 npm install @clayzo/webgl-player，或使用 pnpm add / yarn add / bun add。

### @clayzo/webgl-player 支持 TypeScript 吗？

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

### @clayzo/webgl-player 支持 ESM 还是 CommonJS？

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

### @clayzo/webgl-player 需要什么版本的 Node\.js？

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

### @clayzo/webgl-player 可以商用吗？

@clayzo/webgl-player 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @clayzo/webgl-player 的下载量有多少？

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

### @clayzo/webgl-player 还在维护吗？

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