Shadow Editor Pro 前端架构文档
本文档详细说明 Shadow Editor Pro 前端代码的目录结构和各模块功能。
目录结构概览
src/
├── api/ # API接口调用层
├── assets/ # 静态资源
├── command/ # 命令模式(撤销/重做)
├── components/ # Vue UI组件
├── controls/ # 摄像机控制
├── editor/ # 编辑器核心
├── event/ # 事件系统
├── helper/ # 场景辅助工具
├── loader/ # 资源加载器
├── misc/ # 杂项定义
├── object/ # 3D对象
├── player/ # 场景播放器
├── render/ # 渲染器
├── serialization/ # 序列化
└── utils/ # 工具函数
1. api/ 目录
功能: API接口调用层,封装与服务端通信的接口
结构:
api/
├── request.ts # HTTP请求基础配置
├── 3d/ # 3D资源相关API
│ ├── animation.ts # 动画管理API
│ ├── audio.ts # 音频管理API
│ ├── category.ts # 分类管理API
│ ├── common.ts # 通用类型定义
│ ├── electron.ts # Electron API
│ ├── map.ts # 贴图管理API
│ ├── material.ts # 材质管理API
│ ├── mesh.ts # 模型管理API
│ ├── scene.ts # 场景管理API
│ ├── screenshot.ts # 截图管理API
│ ├── thumbnail.ts # 缩略图管理API
│ ├── typeface.ts # 字体管理API
│ ├── upload.ts # 文件上传API
│ └── video.ts # 视频管理API
└── data/ # 业务数据相关API
├── attribute.ts # 属性管理API
├── device_measure.ts # 设备测量关联API
├── device.ts # 设备管理API
├── dictionary.ts # 字典管理API
├── measure.ts # 测量管理API
├── model_attribute.ts # 模型属性关联API
├── model_device.ts # 模型设备关联API
├── model_measure.ts # 模型测量关联API
└── station.ts # 站点管理API
主要功能:
- 封装所有与服务端的HTTP通信
- 提供3D资源(场景、模型、材质、动画等)的CRUD接口
- 提供业务数据(设备、测量、属性等)的CRUD接口
- 统一处理请求响应格式
- 错误处理和日志记录
使用示例:
import { getSceneList, saveScene } from '@/api/3d/scene'
// 获取场景列表
const result = await getSceneList()
// 保存场景
await saveScene(sceneData)
2. command/ 目录
功能: 命令模式实现,支持撤销/重做操作
结构:
command/
├── Command.ts # 命令基类
├── History.ts # 历史记录管理
├── AddObjectCommand.ts # 添加物体命令
├── MoveObjectCommand.ts # 移动物体命令
├── RemoveObjectCommand.ts # 删除物体命令
├── SetColorCommand.ts # 设置颜色命令
├── SetGeometryCommand.ts # 设置几何体命令
├── SetGeometryValueCommand.ts # 设置几何体参数命令
├── SetMaterialColorCommand.ts # 设置材质颜色命令
├── SetMaterialCommand.ts # 设置材质命令
├── SetMaterialMapCommand.ts # 设置材质贴图命令
├── SetMaterialValueCommand.ts # 设置材质参数命令
├── SetPositionCommand.ts # 设置位置命令
├── SetRotationCommand.ts # 设置旋转命令
├── SetScaleCommand.ts # 设置缩放命令
├── SetSceneCommand.ts # 设置场景命令
├── SetUuidCommand.ts # 设置UUID命令
├── SetValueCommand.ts # 设置值命令
└── MultiCmdsCommand.ts # 批量命令
主要功能:
- 实现命令模式,将操作封装为命令对象
- 支持操作的撤销和重做
- 历史记录管理,记录所有可撤销的操作
- 批量操作支持
使用示例:
import { SetPositionCommand } from '@/command/SetPositionCommand'
// 执行移动命令
editor.execute(new SetPositionCommand(object, new Vector3(1, 2, 3)))
// 撤销
editor.undo()
// 重做
editor.redo()
3. components/ 目录
功能: Vue UI组件库,提供可复用的UI组件
结构:
components/
├── 3d/ # 3D相关组件
│ ├── animation-select-window.vue # 动画选择窗口
│ ├── audio-select-window.vue # 音频选择窗口
│ ├── drag-dialog.vue # 拖拽对话框
│ ├── icon-button.vue # 图标按钮
│ ├── image-button.vue # 图片按钮
│ ├── image-list.vue # 图片列表
│ ├── map-select-window.vue # 贴图选择窗口
│ ├── material-select-window.vue # 材质选择窗口
│ ├── mesh-select-window.vue # 模型选择窗口
│ ├── scene-select-window.vue # 场景选择窗口
│ ├── search-field.vue # 搜索框
│ ├── texture-property.vue # 贴图属性
│ ├── texture-setting-window.vue # 贴图设置窗口
│ ├── toolbar-divider.vue # 工具栏分隔符
│ └── video-player.vue # 视频播放器
└── button/ # 按钮组件
├── base-btn.vue # 基础按钮
└── btn-defs.vue # 按钮定义
主要功能:
- 提供各种3D资源选择对话框
- 图标按钮、图片按钮等通用按钮组件
- 搜索框、图片列表等列表组件
- 贴图、材质等属性编辑组件
- 视频播放器组件
4. controls/ 目录
功能: 摄像机和视图控制
结构:
controls/
├── BaseControls.ts # 控制器基类
├── ControlsManager.ts # 控制器管理器
├── FreeControls.ts # 自由摄像机控制
├── OrbitControls.ts # 轨道控制
└── OrthographicCameraControls.ts # 正交相机控制
主要功能:
- 轨道控制器(OrbitControls):围绕目标旋转
- 自由控制器(FreeControls):自由漫游
- 正交相机控制器:用于工程视图
- 控制器管理:自动切换不同的控制器
使用示例:
// 切换到轨道控制器
controls.setControls('OrbitControls')
// 启用自由漫游
controls.setControls('FreeControls')
5. editor/ 目录
功能: 编辑器核心功能
结构:
editor/
├── Editor.ts # 编辑器主类
├── editor-ui.vue # 编辑器UI
├── assets/ # 资源面板
│ ├── animation-panel.vue # 动画面板
│ ├── audio-panel.vue # 音频面板
│ ├── editor-assets.vue # 资源管理面板
│ ├── map-panel.vue # 贴图面板
│ ├── material-panel.vue # 材质面板
│ ├── mesh-panel.vue # 模型面板
│ ├── scene-panel.vue # 场景面板
│ ├── screenshot-panel.vue # 截图面板
│ └── video-panel.vue # 视频面板
├── assets/window/ # 资源编辑窗口
├── component/ # 组件编辑器
│ ├── animation/ # 动画组件
│ ├── audio/ # 音频组件
│ ├── background/ # 背景组件
│ ├── control/ # 控制组件
│ ├── geometry/ # 几何体组件
│ ├── light/ # 灯光组件
│ ├── line/ # 线条组件
│ ├── material/ # 材质组件
│ ├── object/ # 对象组件
│ ├── physics/ # 物理组件
│ ├── postProcessing/ # 后期处理组件
│ └── shader/ # 着色器组件
├── menu/ # 菜单栏
│ ├── assets-menu.vue # 资源菜单
│ ├── component-menu.vue # 组件菜单
│ ├── edit-menu.vue # 编辑菜单
│ ├── editor-controls.vue # 编辑器控制
│ ├── editor-menu.vue # 编辑器菜单
│ ├── help-menu.vue # 帮助菜单
│ ├── light-menu.vue # 灯光菜单
│ ├── object-menu.vue # 对象菜单
│ ├── options-menu.vue # 选项菜单
│ ├── play-menu.vue # 播放菜单
│ ├── scene-menu.vue # 场景菜单
│ ├── tool-menu.vue # 工具菜单
│ ├── view-menu.vue # 视图菜单
│ ├── visual-menu.vue # 可视化菜单
│ ├── help/ # 帮助子菜单
│ ├── object/ # 对象子菜单
│ ├── options/ # 选项子菜单
│ ├── scene/ # 场景子菜单
│ ├── tool/ # 工具子菜单
│ └── visual/ # 可视化子菜单
├── script/ # 脚本编辑器
├── sidebar/ # 侧边栏
│ ├── animation-panel.vue # 动画面板
│ ├── editor-sidebar.vue # 编辑器侧边栏
│ ├── hierarchy-panel.vue # 层级面板
│ ├── history-panel.vue # 历史面板
│ ├── options-panel.vue # 选项面板
│ ├── property-panel.vue # 属性面板
│ └── script-panel.vue # 脚本面板
├── status/ # 状态栏
│ └── editor-status.vue # 编辑器状态
├── timeline/ # 时间轴
│ └── timeline-panel.vue # 时间轴面板
├── toolbar/ # 工具栏
│ ├── draw-tools.vue # 绘图工具
│ ├── edit-tools.vue # 编辑工具
│ ├── editor-toolbar.vue # 编辑器工具栏
│ ├── general-tools.vue # 通用工具
│ ├── mark-tools.vue # 标记工具
│ └── measure-tools.vue # 测量工具
├── tools/ # 编辑工具
│ ├── AngleTool.ts # 角度测量工具
│ ├── AreaTool.ts # 面积测量工具
│ ├── DigTool.ts # 挖掘工具
│ ├── DistanceTool.ts # 距离测量工具
│ ├── LineMarkTool.ts # 线条标记工具
│ └── PointMarkTool.ts # 点标记工具
└── viewport/ # 视口
├── editor-viewport.vue # 编辑器视口
├── script-panel.vue # 脚本面板
└── visual-panel.vue # 可视化面板
主要功能:
- 编辑器核心类(Editor.ts):管理场景、相机、渲染器等
- 资源面板:管理场景、模型、材质、动画等资源
- 属性面板:编辑选中对象的属性
- 层级面板:显示场景树结构
- 工具栏:提供常用编辑工具
- 菜单栏:提供各种菜单操作
- 组件编辑器:编辑各种组件(灯光、材质、几何体等)
- 脚本编辑器:编写和编辑JavaScript脚本
- 时间轴:管理动画时间轴
- 编辑工具:测量、标记等工具
6. event/ 目录
功能: 事件系统,实现发布-订阅模式
结构:
event/
├── BaseEvent.ts # 事件基类
├── EventDispatcher.ts # 事件分发器
├── EventMap.ts # 事件类型定义
├── AutoSaveEvent.ts # 自动保存事件
├── FilterEvent.ts # 过滤器事件
├── GPUPickEvent.ts # GPU拾取事件
├── LoadSceneEvent.ts # 加载场景事件
├── ObjectEvent.ts # 对象事件
├── PhysicsEvent.ts # 物理引擎事件
├── PickEvent.ts # 拾取事件
├── RaycastEvent.ts # 射线投射事件
├── RenderEvent.ts # 渲染事件
├── ResizeEvent.ts # 窗口调整事件
├── TransformControlsEvent.ts # 变换控件事件
├── ViewEvent.ts # 视图事件
└── WeatherEvent.ts # 天气事件
主要功能:
- 提供完整的事件系统
- 支持事件的注册、分发和监听
- 定义所有事件类型和参数
- 处理各种编辑器事件(选择、渲染、物理等)
事件类型:
- 应用事件:appStart, appStarted, appStop等
- 编辑器事件:sceneGraphChanged, objectSelected等
- 视图事件:resize, raycast, intersect等
- 控制事件:transformControlsChange等
- 侧边栏事件:animationSelected, animationChanged等
使用示例:
import global from '@/global'
// 监听对象选择事件
global.app.event.addEventListener('objectSelected', (e) => {
console.log('选中的对象:', e.object)
})
// 触发事件
global.app.event.dispatchEvent({
type: 'objectSelected',
object: mesh
})
7. helper/ 目录
功能: 3D场景辅助工具(网格、灯光辅助线等)
结构:
helper/
├── BaseHelper.ts # 辅助工具基类
├── Helpers.ts # 辅助工具管理器
├── CameraHelper.ts # 相机辅助器
├── GridHelper.ts # 网格辅助器
├── HoverHelper.ts # 悬停辅助器
├── SelectHelper.ts # 选择辅助器
├── ViewHelper.ts # 视图辅助器
├── animation/ # 动画辅助
├── light/ # 灯光辅助
│ ├── PointLightHelpers.ts # 点光源辅助
│ ├── DirectionalLightHelpers.ts # 平行光辅助
│ ├── HemisphereLightHelpers.ts # 半球光辅助
│ ├── SpotLightHelpers.ts # 聚光灯辅助
│ └── RectAreaLightHelpers.ts # 面光源辅助
├── line/ # 线条辅助
│ └── SplineHelper.ts # 样条曲线辅助
└── shader/ # 着色器辅助
主要功能:
- 网格辅助:显示场景网格
- 灯光辅助:显示灯光范围和方向
- 选择辅助:显示选中物体的高亮
- 悬停辅助:显示鼠标悬停物体
- 视图辅助:显示坐标轴指示器
8. loader/ 目录
功能: 资源加载器,支持40+种3D模型格式
结构:
loader/
├── BaseLoader.ts # 加载器基类
├── ModelLoader.ts # 模型加载器管理
├── AMFLoader.ts # AMF格式加载器
├── BVHLoader.ts # BVH动画加载器
├── ColladaLoader.ts # Collada格式加载器
├── DRACOLoader.ts # Draco压缩加载器
├── FBXLoader.ts # FBX格式加载器
├── GCodeLoader.ts # G-Code加载器
├── GLTFLoader.ts # GLTF格式加载器
├── KMZLoader.ts # KMZ格式加载器
├── MD2Loader.ts # MD2格式加载器
├── MMDLoader.ts # MikuMikuDance加载器
├── NRRDLoader.ts # 医学图像加载器
├── ObjectLoader.ts # Three.js JSON加载器
├── OBJLoader.ts # OBJ格式加载器
├── PCDLoader.ts # 点云数据加载器
├── PDBLoader.ts # 蛋白质数据加载器
├── PLYLoader.ts # PLY格式加载器
├── STLLoader.ts # STL格式加载器
├── TDSLoader.ts # 3DS格式加载器
├── ThreeMFLoader.ts # 3MF格式加载器
├── VRMLLoader.ts # VRML格式加载器
└── VTKLoader.ts # VTK格式加载器
主要功能:
- 支持40+种3D模型格式
- 支持动画格式(BVH, MMD等)
- 支持点云数据(PCD, PLY等)
- 支持医学图像(NRRD)
- 统一的加载接口
支持的格式:
- 模型:.3ds, .3mf, .amf, .bvh, .dae, .drc, .fbx, .gcode, .gltf, .glb, .kmz, .md2, .obj, .pmd, .pmx, .ply, .stl, .vrm, .vrml, .vtk等
- 动画:.vmd(MMD), .vpd(MMD), .bvh等
- 点云:.pcd, .ply等
- 其他:.nrrd(医学图像), .pdb(蛋白质数据)等
使用示例:
import ModelLoader from '@/loader/ModelLoader'
const loader = new ModelLoader()
const model = await loader.load(url, {
type: 'gltf',
clearChildren: true
})
9. misc/ 目录
功能: 杂项定义和工具
结构:
misc/
└── index.d.ts # TypeScript类型定义
主要功能:
- 提供全局类型定义
- 通用工具函数
10. object/ 目录
功能: 3D对象创建和管理
结构:
object/
├── BaseObject.ts # 对象基类
├── component/ # 对象组件
├── geometry/ # 几何体创建
├── light/ # 灯光创建
├── line/ # 线条创建
├── mark/ # 标记创建
├── polygon/ # 多边形创建
├── shape/ # 形状创建
├── text/ # 文本创建
└── weather/ # 天气效果
主要功能:
- 创建各种3D几何体(立方体、球体、圆柱等)
- 创建各种灯光(点光源、平行光、聚光灯等)
- 创建线条和曲线
- 创建标记(点标记、线标记等)
- 创建文本和形状
- 创建天气效果(雨、雪、雾等)
11. player/ 目录
功能: 场景播放器,用于运行和展示场景
结构:
player/
├── Player.ts # 播放器主类
├── EventMap.ts # 播放器事件定义
├── animator/ # 动画播放器
├── component/ # 播放器组件
│ ├── PlayerLoader.ts # 播放器加载器
│ ├── PlayerEvent.ts # 播放器事件处理
│ ├── PlayerControl.ts # 播放器控制
│ ├── PlayerAudio.ts # 音频播放
│ ├── PlayerRenderer.ts # 渲染器
│ ├── PlayerAnimation.ts # 动画播放
│ ├── PlayerEffect.ts # 特效播放
│ ├── PlayerPhysics.ts # 物理引擎
│ ├── WebVR.ts # VR支持
│ └── PlayerAnimation.ts # 动画组件
├── effect/ # 播放器特效
└── component/ # 播放器组件
主要功能:
- 加载和播放场景
- 播放动画(补间动画、骨骼动画等)
- 播放音频
- 物理模拟
- 后期处理效果
- VR支持
使用示例:
import Player from '@/player/Player'
const player = new Player(container, {
server: 'http://localhost:3000',
enablePhysics: true,
showStats: true
})
player.start(sceneData)
// 停止播放
player.stop()
12. render/ 目录
功能: 渲染器和后期处理
结构:
render/
├── BaseRenderer.ts # 渲染器基类
├── EffectRenderer.ts # 效果渲染器
└── shader/ # 着色器
└── *.glsl # GLSL着色器文件
主要功能:
- WebGL/WebGL2/WebGPU渲染器
- 后期处理效果(FXAA, SMAA, SSR, SSAO等)
- 着色器管理
- 自定义着色器支持
支持的效果:
- 抗锯齿:FXAA, SMAA, SSAA, TAA
- 屏幕空间效果:SSAO, SSR
- 特殊效果:Glitch, Halftone, RGB Shift, Bokeh等
13. serialization/ 目录
功能: 场景序列化和反序列化
结构:
serialization/
├── BaseSerializer.ts # 序列化器基类
├── Converter.ts # 转换器
├── Metadata.ts # 元数据
├── app/ # 应用序列化
├── audio/ # 音频序列化
├── camera/ # 相机序列化
├── core/ # 核心序列化
├── geometry/ # 几何体序列化
├── helper/ # 辅助器序列化
├── light/ # 灯光序列化
├── line/ # 线条序列化
├── material/ # 材质序列化
├── objects/ # 对象序列化
└── texture/ # 贴图序列化
主要功能:
- 场景序列化:将场景转换为JSON格式
- 场景反序列化:从JSON加载场景
- 保存场景到服务器
- 从服务器加载场景
- 支持所有Three.js对象的序列化
使用示例:
import { serializeScene } from '@/serialization/Converter'
// 序列化场景
const json = serializeScene(editor.scene, editor.camera)
// 反序列化场景
await loadScene(json)
14. utils/ 目录
功能: 工具函数库
结构:
utils/
├── CanvasUtils.ts # Canvas工具
├── Converter.ts # 转换工具
├── CoordinateUtils.ts # 坐标工具
├── CssUtils.ts # CSS工具
├── DownloadUtils.ts # 下载工具
├── Earcut.ts # 三角剖分
├── Ease.ts # 缓动函数
├── GeometryUtils.ts # 几何体工具
├── ImageUtils.ts # 图片工具
├── MaterialUtils.ts # 材质工具
├── MathUtils.ts # 数学工具
├── MergeUtil.ts # 合并工具
├── MeshUtils.ts # 网格工具
├── MIMETypeUtils.ts # MIME类型工具
├── QueryUtils.ts # 查询工具
├── Storage.ts # 本地存储
├── StringUtils.ts # 字符串工具
├── TextureUtils.ts # 纹理工具
├── TimeUtils.ts # 时间工具
├── TypefaceUtils.ts # 字体工具
├── UploadUtils.ts # 上传工具
└── VideoRecorder.ts # 视频录制
主要功能:
- Canvas操作工具
- 坐标转换工具
- 三角剖分算法
- 缓动函数库
- 几何体操作
- 材质管理
- 纹理处理
- 本地存储封装
- 字符串处理
- 图片处理
- 视频录制
核心类说明
Application
应用程序主类,管理整个应用的初始化和生命周期。
主要方法:
init(): 初始化应用start(): 启动应用dispose(): 释放资源upload(): 文件上传toast(): 显示消息提示alert(): 提示框confirm(): 确认框prompt(): 输入框mask(): 显示加载遮罩unmask(): 隐藏加载遮罩
Editor
编辑器核心类,管理3D场景编辑的所有功能。
主要属性:
scene: Three.js场景camera: 当前相机renderer: 渲染器selected: 当前选中对象history: 历史记录scripts: 脚本列表animations: 动画列表
主要方法:
setScene(): 设置场景clear(): 清空场景addObject(): 添加对象removeObject(): 删除对象select(): 选中对象focus(): 设置焦点execute(): 执行命令undo(): 撤销redo(): 重做
Player
场景播放器,用于运行和展示场景。
主要方法:
start(): 启动播放器stop(): 停止播放器resize(): 调整大小dispose(): 释放资源
事件系统
Shadow Editor Pro 采用发布-订阅模式的事件系统,所有事件类型定义在 event/EventMap.ts 中。
主要事件分类
- DOM事件: click, contextmenu, keydown, mousedown等
- 应用事件: appStart, appStarted, appStop等
- 配置事件: optionChange, storageChanged, themeChanged等
- 工具栏事件: changeMode, changeView, play, stop等
- 编辑器事件: sceneSaved, objectSelected, sceneGraphChanged等
- 视口事件: raycast, intersect, beforeRender, afterRender等
- 侧边栏事件: animationSelected, animationChanged等
- 状态栏事件: enablePhysics, enableVR等
事件使用示例
import global from '@/global'
// 监听事件
global.app.event.addEventListener('objectSelected', (e) => {
console.log('选中对象:', e.object)
})
// 触发事件
global.app.event.dispatchEvent({
type: 'objectSelected',
object: mesh
})
// 移除监听
global.app.event.removeEventListener('objectSelected', handler)
技术栈
- 框架: Vue 3 + TypeScript
- 3D引擎: Three.js
- 构建工具: Vite 4
- UI组件库: Ant Design Vue 4
- 代码编辑器: Monaco Editor
- 状态管理: Pinia
- 路由: Vue Router
开发规范
命名规范
- 文件名:使用kebab-case(如
model-loader.ts) - 类名:使用PascalCase(如
ModelLoader) - 函数/变量:使用camelCase(如
loadModel) - 常量:使用UPPER_CASE(如
MAX_SIZE)
代码组织
- 每个功能模块一个文件
- 导出使用命名导出,默认导出仅用于主类
- 优先使用TypeScript类型定义
- 使用JSDoc注释
注释规范
/**
* 模型加载器
* @author tengge / https://github.com/tengge1
* @since 2024-03-23
*/
class ModelLoader {
/**
* 加载模型
* @param url 模型URL
* @param options 加载选项
* @returns Promise<THREE.Object3D>
*/
load(url: string, options: LoaderOptions): Promise<THREE.Object3D> {
// ...
}
}
性能优化建议
- 对象池: 复用对象,减少创建和销毁开销
- LOD: 使用细节层次(LOD)技术,根据距离调整模型精度
- 实例化: 使用InstancedMesh渲染大量相同物体
- 合并: 合并小的网格,减少绘制调用
- 纹理压缩: 使用压缩纹理格式
- 阴影优化: 限制阴影贴图大小和数量
- GPU拾取: 使用GPU拾取替代射线检测(大场景)
调试技巧
- 查看性能: 使用Stats.js查看FPS
- 日志输出: 使用
global.app.log()输出日志 - 场景检查: 使用
console.log(scene)查看场景结构 - 材质检查: 使用材质编辑器查看材质属性
- 事件追踪: 在EventDispatcher中添加断点追踪事件
常见问题
Q: 如何添加新的模型格式加载器?
A: 在 loader/ 目录下创建新的加载器类,继承 BaseLoader,然后在 ModelLoader.ts 中注册。
Q: 如何添加新的后期处理效果?
A: 在 render/shader/ 目录下添加GLSL着色器文件,然后在 EffectRenderer.ts 中集成。
Q: 如何扩展事件系统?
A: 在 event/EventMap.ts 中添加新的事件类型定义,然后使用 global.app.event.dispatchEvent() 触发事件。
Q: 如何自定义材质?
A: 使用ShaderMaterial或RawShaderMaterial创建自定义材质,或在 editor/component/material/ 中添加材质编辑组件。
相关文档
更新日志
v0.0.1 (2024-10-19)
- 初始版本
- 完整的前端架构文档
- 所有目录功能说明
推荐阅读
评论 (0)
发表评论
暂无评论,快来发表第一条评论吧!