Vue 3 + TypeScript + Three.js GLB 查看器（可复用组件）

封装好的 GLB 交互组件，支持锚点绑定、图标+名称显示、右键菜单、拖拽换锚、连线、相机保存/恢复（含 2D/3D 视角），并暴露完整方法供业务方调用。

� 看不到模型？

如果组件加载成功但看不到 3D 模型，请查看 快速修复指南 👈

🐛 绑定成功但看不到标记？

如果可以点击绑定组件，但看不到标记图标，请查看 标记调试指南 👈

�📚 文档

- 快速上手
- 快速修复：看不到模型 ⭐- 在你的项目中使用 - 直接传递在线 URL 的用法 🔥- 在线 URL 加载问题 - CORS 跨域解决方案
- 使用示例 - 详细的代码示例
- 故障排查 - 完整的问题诊断指南

快速上手（作为依赖使用）

$3

``bash
npm install vue-three-glb-viewer three vue
`

$3

将 .glb 模型文件放到项目的 public/models/ 目录下。

$3

⚠️ 重要：确保容器有明确的高度！

$3

⚠️ 重要：确保容器有明确的高度！

`vue



`

$3

如果组件加载成功但看不到模型，请检查：

1. 容器高度：父容器必须有明确的高度（如 height: 100vh 或 height: 600px）
2. 模型路径：确保模型文件存在于 public/models/model.glb，或指定正确的 modelUrl
3. 控制台错误：打开浏览器控制台（F12）查看是否有加载错误

详细排查步骤请查看 故障排查文档。

> 模型加载可配置：
> - 默认使用静态地址 modelUrl（默认 /models/model.glb）。
> - 可传入 fetchModel，返回 url / Blob / ArrayBuffer（例如从 API 获取），组件会自动创建 object URL 后加载。
> - 若加载失败将回退到默认立方体。
> - 若不希望点击模型自动创建绑定，传入 :enableBindOnClick="false"。
> - 设计/运行模式：传入 :isDesignMode="false" 时仅查看，不可绑定/拖拽/右键取消绑定。

示例：从接口拉取二进制再加载

`ts
const fetchModel = async () => {
const res = await fetch('/api/model')
if (!res.ok) throw new Error('fetch model failed')
return await res.arrayBuffer()
}
`

示例：改用自定义静态地址

`vue

`

暴露的 API（通过模板 ref 调用）

- 相机：
- getCameraState() / setCameraState(state)
- saveCameraToLocalStorage() / loadCameraFromLocalStorage()
- saveCamera2D() / loadCamera2D()
- saveCamera3D() / loadCamera3D()
- 绑定数据：
- getBoundComponentsData(): BoundComponentData[]
- setBoundComponentsData(data: BoundComponentInput[]): boolean
- 图标与元数据：
- setComponentIcon(id, iconSrc)
- setComponentsIcons(iconMap: Record)
- setComponentsMeta([{ id, name?, iconSrc? }, ...])
- 回调：
- setOnBindCallback((component) => void)（用户点击模型新建锚点时触发）
- setOnBindEnd((component) => boolean | void)（绑定结束回调，可用于业务自定义）
- setOnUnbind((componentId) => boolean | void)（取消绑定时触发）
- setOnMarkerClick((component) => void)（用户点击标记时触发）
- setOnMarkerContextMenu((component, event) => boolean | void)（标记右键时触发；返回 false 可阻止默认菜单）
- setOnMarkerDragEnd((component) => boolean | void)（标记拖拽结束时触发）
- unbindComponent(id: number)（直接取消绑定并触发回调）

主要数据结构（从包内导出）：

- CameraState：{ position: {x,y,z}, target: {x,y,z} }
- AnchorData：{ objectUUID: string, local: { x, y, z } }
- BoundComponentData：{ id, name, meshName?, iconSrc, anchor: AnchorData }
- BoundComponentInput：用于导入，anchor 必填，其余可选。

运行与构建（本仓库）

- 开发：npm run dev
- 生产构建：npm run build
- 库构建：npm run build:lib

发布到 npm（提示）

1) 确保 Node ≥ 20.19。2) 更新 package.json 的 version。3) 登录 npm：npm login。4) 发布：npm publish（若包名带 scope 用 npm publish --access public）。

常见问题

$3

可能原因：
- ✅ 模型文件路径不正确：默认模型路径是 /models/model.glb，请确保你的项目中有这个文件，或者传入正确的 modelUrl 属性。
- ✅ 容器没有高度：组件本身高度为 100vh，确保父容器有明确的高度。
- ✅ 没有提供模型数据：如果使用 fetchModel 从 API 加载，确保该函数正确返回数据。

解决方案：

`vue



`

$3

检查以下几点：
- 模型文件是否存在于指定路径
- 服务器是否正确配置了 .glb 文件的 MIME 类型（model/gltf-binary）
- 是否存在跨域问题（CORS）

如果模型加载失败，组件会自动显示一个默认的绿色立方体。

$3

`vue



`

$3

确保在项目中安装了类型依赖：

`bash
npm install --save-dev @types/three
`

然后就可以使用完整的类型提示：

`vue

``

许可证

MIT