3D Stage Editor
一个可嵌入 Web 项目的 3D 场景编辑器,支持场景搭建、人物与机位编辑、轨迹编排,以及图片和视频输出。编辑器在浏览器中运行;场景持久化、文件上传等由接入项目自行实现。
界面预览
舞台编辑
在 3D 视口中选择人物,右侧可调整人物属性。右上角显示机位画面,下方时间轴用于编排轨道。

模型库
在模型库中按类别浏览预置模型,双击模型卡片即可加入场景。

本地运行
在仓库根目录安装依赖并启动开发服务器。
pnpm install --frozen-lockfile
pnpm dev
在浏览器打开 http://127.0.0.1:5175/。
安装
项目提供三个包:
3d-stage-editor:编辑器核心。react-3d-stage-editor:React 封装,支持 React 18 和 19。3d-stage-editor-assets:模型和图片等静态资源。
当前包尚未发布到 npm,以下命令适用于发布后。开发阶段可先构建并安装对应的 npm 压缩包。
npm install 3d-stage-editor 3d-stage-editor-assets
# 使用 React 时额外安装
npm install react-3d-stage-editor
将 3d-stage-editor-assets 安装目录中 dist/assets 的内容复制到网站静态目录,例如 public/stage-assets/。下文的 assetBaseUrl 应指向该目录的访问地址;跨域托管时需要配置 CORS。
JavaScript 接入
<div id="stage" style="width: 100%; height: 800px"></div>
import { createStageEditor } from '3d-stage-editor';
const editor = await createStageEditor({
container: document.querySelector('#stage'),
assetBaseUrl: '/stage-assets/',
scene: null,
onChange: ({ scene, revision }) => {
// 将 scene 保存到自己的服务。
console.log(revision, scene);
},
onRequestClose: async () => {
const { dirty } = await editor.requestClose();
if (!dirty || window.confirm('场景有改动,确定关闭吗?')) {
await editor.destroy();
}
},
onOutputRequest: async (request) => {
const result = request.kind === 'image'
? await editor.capture(request.options)
: await editor.record(request.options);
// 使用 result.blob 上传或下载生成的文件。
console.log(result.filename, result.blob);
},
});
容器必须有明确的宽高。卸载页面或不再使用编辑器时调用 await editor.destroy()。
初始化参数
| 参数 | 必填 | 说明 |
|---|---|---|
container | 是 | 挂载编辑器的 HTML 元素。 |
assetBaseUrl | 是 | 静态资源目录 URL,建议以 / 结尾。 |
scene | 否 | 初始场景数据;null 或不传时创建空场景。 |
readonly | 否 | 是否只读,默认为 false。 |
signal | 否 | AbortSignal,用于取消初始化。 |
onChange | 否 | 场景变化时接收 { scene, revision },由调用方保存。 |
onRequestClose | 否 | 用户点击关闭时触发,由调用方决定是否保存和销毁。 |
onOutputRequest | 否 | 用户请求输出时接收图片或视频参数,由调用方完成导出处理。 |
实例方法
| 方法 | 说明 |
|---|---|
getScene() | 获取当前场景。 |
setScene(scene) | 异步载入场景。 |
setReadonly(value) | 切换只读状态。 |
capture(options, signal?) | 生成图片,返回包含 blob、文件名及尺寸的结果。 |
record(options, signal?, onProgress?) | 生成视频,可接收进度回调。 |
requestClose() | 获取当前场景、修订号与是否有改动。 |
destroy() | 释放编辑器资源。 |
图片参数为 { resolution: '720' | '1080', ratio: '16:9' | '9:16' | '4:3' | '1:1' };视频参数还需提供 startFrame 和 endFrame。录制需要浏览器支持 H.264 编码。
React 接入
import { useRef } from 'react';
import { StageEditor, type StageEditorHandle } from 'react-3d-stage-editor';
export function Editor() {
const ref = useRef<StageEditorHandle>(null);
return (
<StageEditor
ref={ref}
assetBaseUrl="/stage-assets/"
style={{ width: '100%', height: 800 }}
onChange={({ scene }) => console.log(scene)}
onOutputRequest={async (request) => {
const editor = ref.current?.getEditor();
if (!editor) return;
const result = request.kind === 'image'
? await editor.capture(request.options)
: await editor.record(request.options);
console.log(result.blob);
}}
onError={(error) => console.error(error)}
/>
);
}
React 组件还支持 initialScene、readonly、className、onRequestClose 和 onReady。组件卸载时会自动销毁编辑器;初始化后的场景更新可通过 ref.current?.getEditor()?.setScene(scene) 完成。