# @alpha2-sh/editor 中文文档
规范地址：https://npmcn.com/package/%40alpha2-sh/editor/
版本：0\.5\.3
npm 元数据更新时间：2026-11-04T23:26:57.368Z
中文译文更新时间：2026-11-06T13:38:44.805Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40alpha2-sh/editor
原文对照：https://npmcn.com/package/%40alpha2-sh/editor/?lang=original
项目主页：https://github.com/alpha2-sh/alpha2#readme
源码仓库：https://github.com/alpha2-sh/alpha2
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：793 kB，101 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^19\.3\.0，alpha2 0\.5\.3
- 首次发布：2026-10-19T20:36:15.711Z
- 最新版本发布：2026-11-04T23:26:57.019Z
- 近 30 天下载量：3102（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）
## 中文简介
无头项目编辑会话和Alpha2的浏览器适配器.
## 安装
```sh
npm install @alpha2-sh/editor
```
也可以使用：`pnpm add @alpha2-sh/editor`、`yarn add @alpha2-sh/editor`、`bun add @alpha2-sh/editor`
## README
# @alpha2-sh/编辑
A. 编辑 SDK for alpha2: 在引擎项目文档上编辑会话, 并有输入命令、 校验和撤销, 以及浏览器桥接, 用于预览、 播放和导出文档 [`alpha2`](https://github.com/alpha2-sh/alpha2/blob/main/packages/alpha2/README.md) 发动机.
## 安装
```sh
npm install @alpha2-sh/editor alpha2
```
`alpha2` 是一个与此软件包相同的版本的对等依赖。 反应是一个可选的对等方,仅需要用于 `@alpha2-sh/editor/react` (反应19.3或后19. 浏览器要求是 `alpha2`对.
## 文档和命令
Root导入是编辑核心. 它没有装入DOM,React,Web Assembly或音频,所以它也在Node.js中运行.
```js
import { createEditor, createEmptyDocument, serializeDocument, parseDocument } from "@alpha2-sh/editor";
const editor = createEditor({ document: createEmptyDocument({ width: 1280, height: 720 }) });
const result = editor.dispatch({
type: "track.add",
track: { id: "video", name: "Video", kind: "video", clips: [] },
});
if (!result.ok) throw result.error; // an EditorError with a `code`
editor.undo();
editor.redo();
const json = serializeDocument(editor.document); // portable JSON; media bytes stay apart
const reopened = parseDocument(json);
editor.dispose();
```
- 编辑器文档持有一个引擎工程( Name`document.project`),编辑元数据,以及每个资产的描述符. `serializeDocument` 财务报告和审定财务报表 `parseDocument` 写作并读作JSON; `parseDocument` 还读取了平版引擎项目.
- `dispatch` 应用一个 `Command` (被键入的结合涵盖项目、音轨、剪辑、效果、过渡、标题提示、组成图、资产和标记);a `transaction` 应用若干项,并按其结尾的文档检查一次。 命令文件的规则拒绝返回 `{ ok: false, error }` 改变什么. `canExecute` 问而不应用.
- 每一个变化都是一步之遥。 历史持续到120步,默认为64米B(`createEditor({ historyLimit, historyByteLimit })`) (中文(简体) ).
- `beginGesture()` 预览拖曳:每个 `update(command)` 显示在 `editor.draft` 不接触文件或历史 `commit()` 添加一个倒数步骤( e)`cancel()` 页:1.
- `subscribe`, (中文(简体) ), `getSnapshot` 财务报告和审定财务报表 `subscribeSelector` 通知更改的意见。 拒绝是 `EditorError`,其 `code` 显示哪个检查失败 .
## 浏览器桥
`@alpha2-sh/editor/browser` 连接一个会话到浏览器中的引擎:导入,预览,用音频回放,并通过WebCodecs导出到一个MP4,MOV,MKV或WebM文件.
```js
import { createEditor, createEmptyDocument } from "@alpha2-sh/editor";
import { createBrowserBridge } from "@alpha2-sh/editor/browser";
const editor = createEditor({ document: createEmptyDocument({ width: 1280, height: 720 }) });
const bridge = createBrowserBridge({
editor,
// URLs of alpha2/wasm/alpha2_wasm_bg.wasm, alpha2/wasm/alpha2_audio_worklet.wasm and
// alpha2/audio-worklet-processor, as the application's bundler serves them.
runtimeAssets: { wasmUrl, audioWasmUrl, workletUrl },
});
await bridge.bindPreview(canvas);
const { assetIds } = await bridge.importFiles(files); // from an
const trackId = crypto.randomUUID();
const placed = editor.dispatch({
type: "transaction",
commands: [
{ type: "track.add", track: { id: trackId, kind: "video", name: "Video", clips: [] } },
{
type: "clip.insert",
trackId,
clip: {
id: crypto.randomUUID(),
source_id: assetIds[0],
timeline_range: { start: 0, end: 120000 },
source_range: { start: 0, end: 120000 },
time_map: { type: "forward" },
},
},
],
});
if (!placed.ok) throw placed.error;
await bridge.seek(0);
const artifact = await bridge.startExport({ container: "webm" }).result;
// artifact.kind "file": a temporary file in the origin's private storage; release it once downloaded.
if (artifact.kind === "file") await artifact.release();
await bridge.dispose();
await editor.dispose();
```
- 导入以引擎检查每个文件( 介质, 字体, ), `.cube` LUT, SRT 和 WebVTT 字幕通过 `importCaptions`),并添加到文档中一个可撤销的步骤. `importSequence` 导入 PNG 或 OpenEXR 文件为一图像序列。 提供者未读取文件的源, 如 LaTeX 公式(`{ format: "latex", latex, font_size }`),保留在项目本身中: `putProviderSource` 在一个可撤销的步骤中添加或编辑一个,它在预览和两个导出中都画出没有重链接的文件.
- `bindPreview` 画布上画的 与 `runtimeAssets.workerFactory`,一个工人运行 `@alpha2-sh/editor/preview-worker` 条目使预览脱离了主线;没有主线,或者当工人失败时,主线就是主线. `hashWorkerFactory` (单位:千美元)`@alpha2-sh/editor/hash-worker`和 `extensionsWorkerFactory` (单位:千美元)`@alpha2-sh/editor/extensions-worker`,与 `extensionsWasmUrl` 财务报告和审定财务报表 `extensionModuleUrls` 例如 `{ pdf }`)将文件散列和SVG,动画图像,洛蒂,OpenEXR和PDF读取到工人中去.
- `seek`, (中文(简体) ), `play` 财务报告和审定财务报表 `pause` 移动播放头; 有音频, 回放跟随音频时钟。 音频预览需要交叉出处的孤立页面;编辑和视频预览则不.
- `startExport` 返回一个工作 `result`,进展(`subscribe`和 `cancel`。 。 。 . `container` (单位:千美元)`mp4` 默认, `mov`, (中文(简体) ), `mkv` 或者说 `webm`命名文件和决定解码器:缺席 `videoCodec` 或者说 `audioCodec` 是容器的默认值(H.264和AAC,或WebM的VP9和Opus,其中浏览器不能将AAC编码入MP4或MKV),而一个容器不提供,被拒绝。 输出默认会转到来源的私人存储中的临时文件( O) :`release()` 删除它),用户选择的文件(`output: { kind: "file", handle }`),或为内存(`output: { kind: "memory", maxBytes }`) (中文(简体) ). 浏览器是否编码了可解码器,是浏览器说: `bridge.videoEncoders()` 询问前面,浏览器没有编码的导出会被拒绝.
## 反应
`@alpha2-sh/editor/react` 已经 `EditorProvider`, (中文(简体) ), `useEditor`, (中文(简体) ), `useEditorSelector(selector, equal?)` 财务报告和审定财务报表 `EditorPreview`,将桥的预览与它制作的画布结合:
```jsx
```
应用程序拥有会话:卸载提供者不处理会话.
## 本地导出
`@alpha2-sh/editor/native-client` (单位:千美元)`createNativeClient({ baseUrl })`) 输出应用程序运行的HTTP出口服务文件,例如: [`@alpha2-sh/node`](https://github.com/alpha2-sh/alpha2/blob/main/packages/alpha2-node/README.md)上传文档的媒体(`bridge.nativeAssets`)并跟踪工作到可下载文件.
## 许可证
MIT,版权Alpha2贡献.
## 常见问题
### @alpha2-sh/editor 是什么？
无头项目编辑会话和Alpha2的浏览器适配器\.
### 如何安装 @alpha2-sh/editor？
在项目目录运行 npm install @alpha2-sh/editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：alpha2（0\.5\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @alpha2-sh/editor 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @alpha2-sh/editor 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @alpha2-sh/editor 可以商用吗？
@alpha2-sh/editor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @alpha2-sh/editor 的下载量有多少？
根据 npm 官方下载统计，@alpha2-sh/editor 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,102 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @alpha2-sh/editor 还在维护吗？
最新版本 0\.5\.3 发布于 2026/11/05（2 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。