# @flighthq/sdk 中文文档

规范地址：https://npmcn.com/package/%40flighthq/sdk/

版本：0\.6\.0
npm 元数据更新时间：2026-11-10T19:40:05.317Z
中文译文更新时间：2026-11-14T23:03:42.593Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：230 kB，639 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：155 个
- 首次发布：2026-07-10T06:04:51.101Z
- 最新版本发布：2026-11-10T19:40:04.851Z
- 近 30 天下载量：8740（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：428（近 12 个月 428 个）

## 中文简介

单一切入点再出口所有软件包

## 安装

```sh
npm install @flighthq/sdk
```

也可以使用：`pnpm add @flighthq/sdk`、`yarn add @flighthq/sdk`、`bun add @flighthq/sdk`

## README

# 飞行

[![CI](https://github.com/flighthq/flight/actions/workflows/tests.yml/badge.svg?branch=develop)](https://github.com/flighthq/flight/actions/workflows/tests.yml?query=branch%3Adevelop) [![npm](https://img.shields.io/npm/v/@flighthq/sdk?logo=npm)](https://www.npmjs.com/package/@flighthq/sdk)

Flight是用于构建交互式应用程序的模块化TypeScript SDK——设计由AI编码代理以及人阅读并编写. 其超过150个可树可摇动的包跨出2D和3D图形,物理,动画,媒体,输入,资产格式,应用程序生命周期,以及桌面/移动平台API.

API是蜂窝:明确通过简单数据,自我识别姓名,明确所有权,输入时没有工作. 一个函数可以孤立地理解;一个应用程序可以导入一个能力而无需继承一个引擎. 同样的特性使密码库可以复制给物剂、可移植到编译目标、生产建筑小.

一次构建一个场景并选择一个渲染器——Canvas 2D,DOM,WebGL 2或WebGPU——只注册它所使用的执行. 将同样的小原始物编成游戏,可视化,媒体体验,桌面工具,或移动应用程序.

## 试试看

看,飞行会自己变的 [现场介绍](https://flighthq.ai/)浏览 [示例库](https://flighthq.ai/examples/)比较 [现有框架的端口](https://ports.flighthq.ai/),或在当地运行画廊:

```sh
npm install
npm run examples
```

## 开始

```sh
npm install @flighthq/sdk
```

创建显示对象场景,注册您使用的渲染器类型,更新渲染图,然后绘制:

```ts
import { webCanvasRenderSurfaceCreator } from '@flighthq/host-web';
import {
  addNodeChild,
  beginCanvasRenderPass,
  createCanvasElement,
  createCanvasRenderState,
  createCanvasRenderSurface,
  createCanvasScreenRenderTarget,
  createCanvasTextureResolvers,
  createDisplayObject,
  createSprite,
  createTexture,
  canvasSpriteRenderer,
  endCanvasRenderPass,
  getCanvasRenderStateTextureResolvers,
  loadImageResourceFromUrl,
  prepareScene2DRender,
  registerCanvasImageTextureResolver,
  registerNodeRenderer,
  renderCanvasScene2D,
  scene2DCanvasPipeline,
  SpriteKind,
} from '@flighthq/sdk';

const pixelRatio = window.devicePixelRatio || 1;
const canvas = createCanvasElement(webCanvasRenderSurfaceCreator, 550, 400, pixelRatio);
document.body.appendChild(canvas);

// Where the frame lands is a render target; how it is drawn is the render state. They are separate
// values, joined for the duration of a pass.
const screen = createCanvasScreenRenderTarget(
  createCanvasRenderSurface(webCanvasRenderSurfaceCreator, canvas, {
    height: canvas.height / pixelRatio,
    pixelRatio,
    width: canvas.width / pixelRatio,
  }),
);
const state = createCanvasRenderState(
  scene2DCanvasPipeline,
  createCanvasTextureResolvers(webCanvasRenderSurfaceCreator),
  { sceneGraphSyncPolicy: 'requiresInvalidation' },
);
// The background is what the pass clears to — a per-pass colour in linear float RGBA, not a field the
// render state carries around.
const screenClear = { color: [0xee / 0xff, 0xdd / 0xff, 0xcc / 0xff, 1] } as const;

registerCanvasImageTextureResolver(getCanvasRenderStateTextureResolvers(state));
registerNodeRenderer(state, SpriteKind, canvasSpriteRenderer);

const root = createDisplayObject();
root.scaleX = pixelRatio;
root.scaleY = pixelRatio;

const sprite = createSprite();
const image = await loadImageResourceFromUrl('assets/wabbit_alpha.png');
sprite.data.texture = createTexture({ dimension: '2d', source: image });
addNodeChild(root, sprite);

function enterFrame(): void {
  if (prepareScene2DRender(state, root)) {
    const pass = beginCanvasRenderPass(state, screen, screenClear);
    renderCanvasScene2D(pass, root);
    endCanvasRenderPass(pass);
  }

  requestAnimationFrame(enterFrame);
}

enterFrame();
```

同一场景通过DOM,WebGL2或WebGPU,通过创建匹配的渲染状态并注册后端的渲染器——对场景图本身没有变化. 显示对象保持纯数据;后端工作仍然清晰.

### 动画

应用软件包提供请求-激活-帧回路,并有打入的更新并渲染出信号. 主机执行是明确的;在浏览器中,在启动应用程序时通过网页主机:

```sh
npm install @flighthq/host-web
```

```ts
import { webHost } from '@flighthq/host-web';
import {
  connectSignal,
  createAppLoop,
  createTween,
  createTweenManager,
  easeOutElastic,
  invalidateNodeRender,
  startAppLoop,
  updateTweens,
} from '@flighthq/sdk';

const manager = createTweenManager();

const tween = createTween(manager, sprite, 1000, { x: 400, alpha: 0 }, { ease: easeOutElastic });
connectSignal(tween.onUpdate, () => invalidateNodeRender(sprite));

const app = createAppLoop();
connectSignal(app.onUpdate, (delta) => updateTweens(manager, delta));
connectSignal(app.onRender, () => {
  if (prepareScene2DRender(state, root)) {
    const pass = beginCanvasRenderPass(state, screen, screenClear);
    renderCanvasScene2D(pass, root);
    endCanvasRenderPass(pass);
  }
});

startAppLoop(webHost, app);
```

### 互动

任何场景节点的线起指针事件. 注册一次命中测试策略,然后创建一个交互管理器并将其连接到输入系统:

```ts
import {
  attachPointerInput,
  connectInputToInteraction,
  connectInteractionSignal,
  createInputManager,
  createInteractionManager,
  invalidateNodeRender,
  registerDefaultHitTests,
  setNodeHitTestEnabled,
} from '@flighthq/sdk';

registerDefaultHitTests();
setNodeHitTestEnabled(sprite, true);

const interaction = createInteractionManager(root);
const input = createInputManager();
attachPointerInput(input, canvas);
connectInputToInteraction(input, interaction, pixelRatio);

connectInteractionSignal(interaction, sprite, 'onPointerDown', () => {
  sprite.alpha = 0.5;
  invalidateNodeRender(sprite);
});
connectInteractionSignal(interaction, sprite, 'onPointerUp', () => {
  sprite.alpha = 1;
  invalidateNodeRender(sprite);
});
```

### 声音

用倒置格式装入音频资源, 然后播放 :

```ts
import { loadAudioResourceFromUrls, playAudioResource } from '@flighthq/sdk';

const audioContext = new AudioContext();
const sound = await loadAudioResourceFromUrls(audioContext, [{ url: 'assets/click.ogg' }, { url: 'assets/click.mp3' }]);

connectInteractionSignal(interaction, sprite, 'onPointerDown', () => {
  playAudioResource(audioContext, sound);
});
```

## 渲染模型

飞行将作者数据与后端工作分离:

1.  从显示对象,图示,文本,形状,平面,微粒,或3D场景节点来构建一个图.
2.  为 Canvas 2D, DOM, WebGL2 或 WebGPU 创建后端渲染状态.
3.  仅记录渲染器和效果后端的场景需要.
4.  执行明确的准备/更新通过.
5.  通过选中的后端绘制 .

Canvas和DOM是轻量级主机-web路径. WebGL2 和 WebGPU 添加 GPU 渲染目标,缓存管,遮蔽/材料注册,后处理,剪接,遮蔽,速度,渲染缓存,2D分批,并用一个20-材料 Cook-Torrance PBR + Classic/NPR/debug 遮蔽库的3D前置渲染器.

## 平台范围

目前飞行跨度超过150个独立可导入,可公布的包. 可通过下列方式对公众API进行检查:

```sh
npm run api
npm run api -- --json
```

主要领域:

| 区域 | 软件包 |
| --- | --- |
| 核心和数据 | `types`, (中文(简体) ), `entity`, (中文(简体) ), `node`, (中文(简体) ), `signals`, (中文(简体) ), `math`, (中文(简体) ), `geometry`, (中文(简体) ), `color`, (中文(简体) ), `layout`, (中文(简体) ), `compression` |
| 2D 图形 | `scene2d`, (中文(简体) ), `bitmap`, (中文(简体) ), `shape`, (中文(简体) ), `path`, (中文(简体) ), `clip`, (中文(简体) ), `text`, (中文(简体) ), `tilemap`, (中文(简体) ), `quadbatch` |
| 三维图形 | `scene3d`, (中文(简体) ), `mesh`, (中文(简体) ), `materials`, (中文(简体) ), `shading`, (中文(简体) ), `lighting`, (中文(简体) ), `texture`, (中文(简体) ), `camera`, (中文(简体) ), `skeleton3d`, (中文(简体) ), `picking` |
| 渲染 | `render`, Canvas/DOM 场景渲染器,WebGL 2和WebGPU核心,以及2D/3D GPU渲染器 |
| 效果和成像 | `adjustments`, (中文(简体) ), `effects`, Canvas/WebGL/WebGPU 效果执行器, `image`, (中文(简体) ), `image-codec`, (中文(简体) ), `capture` |
| 文本 | `textlayout`, (中文(简体) ), `textshaper`, (中文(简体) ), `textsegment`, (中文(简体) ), `textbidi`, (中文(简体) ), `textinput`, (中文(简体) ), `glyphatlas`, (中文(简体) ), `bitmapfont`, (中文(简体) ), `bitmaptext`, (中文(简体) ), `text-markup` |
| 动画和模拟 | `easing`, (中文(简体) ), `tween`, (中文(简体) ), `spring`, (中文(简体) ), `animation`, (中文(简体) ), `timeline`, (中文(简体) ), `movieclip`, (中文(简体) ), `spritesheet`, (中文(简体) ), `motionpath`, (中文(简体) ), `clock`, (中文(简体) ), `particles` |
| 游戏和互动 | `input`, (中文(简体) ), `interaction`, (中文(简体) ), `collision`, (中文(简体) ), `physics2d`, (中文(简体) ), `spatial`, (中文(简体) ), `flow`, (中文(简体) ), `statechart`, (中文(简体) ), `snapshot` |
| 资源和格式 | 图像、字体、地图集、平面图、粒子、SVG、SWF、glTF、OBJ/MTL、3DS、MD2/MD5、AWD2等的装入器和结构化进口商 |
| 申请和媒体 | `app`, (中文(简体) ), `audio`, (中文(简体) ), `video`, (中文(简体) ), `media`, (中文(简体) ), `mediasession`, (中文(简体) ), `intl`, (中文(简体) ), `log`, (中文(简体) ), `debug` |
| 平台整合 | 用于存储、联网、文件系统、剪贴板、对话框、通知、传感器、窗口、生命周期和其他操作系统/设备的网络首个API |
| 本地主机 | 明确 `Host` 电子、陶里和电容的值 |
| 工具 | 采集和基线工具、交接烟雾/公平检查、合规装置、API/出口/包装/订单/可移动性门和捆绑规模的预算 |

所有软件包都在 `@flighthq/`。应用程序和实例通常从 `@flighthq/sdk`数字 :

```ts
import { addNodeChild, createBitmap, createShape } from '@flighthq/sdk';
```

库代码应该选择提供所需 API 的最小包根 :

```ts
import { createTween, updateTweens } from '@flighthq/tween';
```

平台 `Host` 价值观是明确的。 浏览器应用程序通过现成 `webHost` 或窄处 `webHost*` 值; Tauri 和 Capacitor 应用程序构造 `tauriHost` 或者说 `capacitorHost` 从他们注入的本地API。 在这些主机中,应用程序的API保持稳定.

## 工程信心

飞行是预放软件,所以信心来自每次改变背后的工程路径. 代码的更改通过两个单元测试道进行,一个完整的TypeScript构建,软件包和公-API验证,捆绑大小的预算,以及浏览器在DOM,Canvas,WebGL,和WebGPU之间的发烟和等价检查. 夜间运行增加了覆盖阈值并产生了API-地表检查.

`main` 是一个机器管理的有名有实的指针:它只推动其CI运行成功。 版本发布在以出处向 npm 发布完整包图之前, 验证精确标记的承诺通过 CI .

该储存库还将可靠性方面的关注保留在设计中:进口是无副作用的,特色家庭使用明确的登记簿,资源所有权和分配被命名,格式进口商报告结构化诊断,来源留在已检查的已汇编的可携带目标子集内,并且通过可互换的后端测试产出.

## 实例

画廊包括有重点的例子,包括形状、文字、互动、动画、瓷砖、颗粒、相撞、应用流程、音频/视频、文件格式加载,以及涵盖材料、取取取和取取火的三维场景。 在共享能力的地方,画廊允许您在支持的渲染器中切换相同的场景.

创建具体实例:

```sh
npm run build --workspace=examples/packages/shapes
```

运行一个特定的渲染器实例 Dev 服务器 :

```sh
npm run dev:canvas --workspace=examples/packages/shapes
npm run dev:dom --workspace=examples/packages/shapes
npm run dev:webgl --workspace=examples/packages/shapes
npm run dev:webgpu --workspace=examples/packages/scene3d
```

## 仓库

```sh
git clone https://github.com/flighthq/flight.git
cd flight
npm install
```

```text
packages/      Workspace packages published as @flighthq/*
examples/      Standalone Vite example apps
conformance/   Import fixtures and structured conformance checks
tools/         Gallery, functional scenes, capture harness, and repo utilities
scripts/       Validation, API, coverage, ordering, size, and build scripts
```

有用的检查 :

```sh
npm run check              # package, type, API, export, portability, docs, and style gates
npm run test               # unit tests across all packages
npm run size               # gzip output size against committed budgets
npm run test:smoke         # fail on browser/runtime/render errors
npm run test:parity        # compare output across render backends
npm run test:regression    # compare output against committed fingerprints
```

## 常见问题

### @flighthq/sdk 是什么？

单一切入点再出口所有软件包

### 如何安装 @flighthq/sdk？

在项目目录运行 npm install @flighthq/sdk，或使用 pnpm add / yarn add / bun add。

### @flighthq/sdk 支持 TypeScript 吗？

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

### @flighthq/sdk 支持 ESM 还是 CommonJS？

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

### @flighthq/sdk 可以商用吗？

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

### @flighthq/sdk 的下载量有多少？

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

### @flighthq/sdk 还在维护吗？

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