three.js 编辑器与 React 项目集成
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()释放资源。
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
}结语
three.js 编辑器的跨框架特性让 React 团队也能享受低代码 3D 能力。通过合理的 Hooks 封装、状态分层与 TypeScript 类型增强，React 应用可以与 three-edit-cores 形成稳定高效的协作关系。