three.js 编辑器与 React 项目集成

2026/7/30 12:58:00

three.js 编辑器与 React 项目集成

本文围绕three.js 编辑器（一款基于 Three.js 的 AI 驱动可视化低代码编辑器）展开。

- 🌐 在线预览： https://z2586300277.github.io/threejs-editor/

- 📦 GitHub 开源仓库： https://github.com/z2586300277/three-editor

- 📚 文档地址： https://z2586300277.github.io/three-editor/docs/dist

虽然 three.js 编辑器的 UI 层使用 Vue3，但其 3D 内核three-edit-cores是纯 JavaScript/TypeScript 运行时，天然可以脱离 Vue 使用。这意味着 React 项目同样能够集成编辑器的全部渲染、交互与扩展能力，而不会受到框架差异的限制。

一、three-edit-cores 的跨框架能力

three-edit-cores只依赖 Three.js 与浏览器 API，不绑定任何前端框架。React 应用只需要一个 DOM 容器，即可实例化ThreeEditor并接管后续所有 3D 渲染、事件与场景管理。这种跨框架特性是编辑器能够服务不同技术栈团队的根本原因。

二、React 封装思路

推荐将编辑器封装为一个受控 React 组件：

使用useRef获取画布容器。
在useEffect中异步初始化ThreeEditor。
通过useImperativeHandle或回调把编辑器实例暴露给父组件。
在清理函数中调用destroySceneRender()释放资源。

这种模式与 Vue 的emitThreeEditor思路等价，只是换成了 React 的 Hooks 语义。

三、Hooks 封装示例

可以进一步封装useThreeEditorHook，统一管理初始化状态、窗口缩放、场景参数加载与保存。业务页面只需调用 Hook，就能获得loading、editorRef、saveScene等语义化能力。TypeScript 用户还可以为 Hook 补充类型定义，提升协作体验。

四、状态同步

React 的状态系统与 Three.js 的场景对象是两套模型。建议把「场景配置」作为 React state，在保存/加载时与threeEditor.saveSceneEdit()和resetEditorStorage()进行转换；而运行时的选中、变换、动画等高频状态则留在编辑器内部，避免不必要的 React 重新渲染。对于需要把外部数据映射到 3D 元素的场景，可以通过useEffect监听数据变化并调用编辑器 API。

五、TypeScript 类型增强

如果项目使用 TypeScript，可以为编辑器实例与组件参数补充类型声明。例如，定义SceneEditorProps接口约束sceneParams、onReady、className等属性；为useThreeEditor返回的 ref 声明ThreeEditor类型。类型安全不仅降低协作成本，也能在升级内核时快速发现不兼容变更。

六、与 Next.js 结合

在 Next.js 中使用 three.js 编辑器时，由于 Three.js 依赖浏览器 API，必须通过next/dynamic关闭服务端渲染，再在客户端组件中初始化编辑器。同时注意 Next.js 的图片优化与路由预取不会直接作用于 WebGL 纹理，需要自行管理资源加载策略。

代码一瞥

import { useEffect, useRef } from 'react'import { ThreeEditor } from 'three-editor-cores'
export default function SceneEditor({ sceneParams, onReady }) { const containerRef = useRef(null) const editorRef = useRef(null)
useEffect(() => { if (!containerRef.current) return const editor = new ThreeEditor(containerRef.current, { webglRenderParams: { antialias: true, alpha: true }, sceneParams }) editorRef.current = editor onReady?.(editor)
const handleResize = () => editor.renderSceneResize?.() window.addEventListener('resize', handleResize)
return () => { window.removeEventListener('resize', handleResize) editor.destroySceneRender() } }, [])
return
}