GitHub查看源仓库更新于 2026/11/21 08:16:11

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) 完成。