导语：在网页里自由摆放 3D 模型
- 本项目当前聚焦"纯三维摆放与交互"的能力，不涉及摄像头与图像识别，后续会增加此功能。
- 适合快速做原型、演示布局、测试交互与材质效果。
快速上手
- 安装依赖：
pnpm install - 启动开发：
pnpm dev后访问本地服务首页，进入 WebAR 演示页即可体验 - 调试建议：先用桌面浏览器进入"模拟模式"，再用支持 WebXR 的手机浏览器体验"真实 AR"， 后续有设备后增加 ！
项目截图
技术栈一览（选择理由）
- React + TypeScript + Vite：现代前端组合，开发体验与类型安全兼顾；Vite 启动与热更非常快。
- Three.js：浏览器端主流 3D 引擎，生态丰富，适合快速搭建 3D 场景与材质光照。
- Tailwind + React Router：快速构建 UI 与页面导航。
- 当前版本不涉及摄像头与图像识别。
架构总览（文字版）
- UI 层：页面上的"启动/停止、添加模型、网格编辑、标记检测"等操作与状态显示。
- 会话管理：统一控制 AR 会话的生命周期，把底层事件转换成"开始/结束/帧更新"等上层语义。
- 核心引擎：负责 Three.js 场景、相机、渲染循环、性能监控，以及与"标记检测/模型加载"的协作。
- 交互系统：把触摸、鼠标、键盘、语音、游戏手柄输入，转成"点击、拖拽、缩放、旋转、滑动、双击"等动作事件。
- 当前版本专注 3D 场景与交互，不包含摄像头/图像/二维码等识别功能。
- 模型加载：GLTF/GLB 首选，内置缓存与失败兜底（彩色立方体），还支持快速几何与文字模型。
事件流示意（简化）
- 用户点击"启动" → 会话管理创建并启动会话 → 引擎开始渲染循环 → 性能指标同步更新
- 用户在画布交互 → 交互系统把输入转成动作事件 → 选中对象并附着变换控制器 → 执行移动/旋转/缩放
（当前版本无"标记检测/摄像头"分支）
生命周期（分步）
- 初始化：创建会话管理与引擎、渲染器、场景基础光照；准备交互系统
- 会话启动：检查 WebXR 支持；支持则启用真实 AR；不支持则进入"模拟模式"（虚拟平面与帧数据）
- 渲染循环：统计 FPS、帧时、绘制调用、三角形数；按帧驱动 UI 与可视化
- 交互控制：对象选中、拖拽、缩放、旋转、命令执行（含中文自然语言）
- 停止与清理：停止会话/检测、释放资源（模型、纹理、监听器），回到初始状态
核心模块深入
引擎
- 维护场景、相机与渲染器；在"模拟模式"下提供虚拟平面与帧数据，确保桌面也能体验
- 统一事件出口：会话、模型加载、标记检测、帧更新、性能信息
会话管理
- 提供"启动/停止/重置"等入口，屏蔽底层差异（WebXR 与模拟模式）
- 把引擎事件规范化为上层语义，页面无需关心底层实现
交互系统
- 手势：支持点击/双击、拖拽、缩放（捏合/滚轮）、旋转（右键/双指上滑）、滑动识别
- 键盘：
Q/E/W/S快速旋转；F翻转（世界/视图/局部三种模式） - 语音：中文识别管道，示例指令"旋转 30 度""放大 10%"
- 游戏手柄：基础按钮与摇杆轮询，映射为移动/旋转等事件
（本版不包含标记识别与摄像头功能）
模型加载
- GLTF/GLB 首选；失败时自动生成彩色立方体占位，保证"场景可见"与可继续调试
- 快速构造：一键生成常用几何体与文字贴图平面，用于占位与标签
进阶操作
- 网格编辑：打开网格后进入编辑模式，附着变换控制器进行移动/旋转/缩放；适合场景对齐与参考
- 吸附步长：为位移/旋转/缩放设置步长，提升精度与一致性；适合对齐标记或构建规范化布景
- 自然语言命令：支持中文指令解析，建议明确单位（度/百分比/米）；避免含混表达
性能优化清单
- 减负：尽量减少高细分几何与复杂着色；阴影与发光效果按需使用
- 资源：控制纹理尺寸与数量；模型复用与缓存；及时释放不再可见的对象
- 事件：对滚轮/拖拽等高频事件做节流或去抖；避免频繁状态更新导致重绘抖动
- 监控：关注 FPS、帧时、绘制调用、三角形数；当 FPS 明显下降时，优先检查"场景复杂度"与"纹理大小"
（本版不涉及摄像头/麦克风权限- 有点问题，后续优化）
场景案例
- 教育：在课本封面上叠加 3D 动画，点击触发解说
- 营销：在产品包装上浮现模型与热点，引导互动与转化
- 导览：展馆中以二维码或图像标记触发导览模型，支持多标记切换
FAQ 扩展
- 如何导入 GLB 模型：通过工具栏"预设模型"或"本地导入"入口；导入后可用变换控制器编辑位置/旋转/缩放。
- 吸附步长如何设置：在工具栏中打开"吸附"并调整位移/旋转/缩放的步长数值，便于精确对齐。
- 无法选中物体怎么办：确保未点击到网格线或描边；可切换编辑模式或点击物体的主体区域重试。
术语小词典
- 射线投射：从相机到场景发射"射线"来命中对象的技术
- GLTF/GLB：Web 场景常用的 3D 模型格式
- 帧时（Frame Time）：渲染一帧所需时间，影响流畅度