vue-3d-model-viewer

一个基于Three.js的Vue 3D模型查看器组件，支持加载GLTF/GLB格式的3D模型，提供丰富的交互和渲染控制功能。

功能特性

• 🎯 支持GLTF/GLB格式模型加载
• 🎛️ 丰富的渲染参数控制（金属度、粗糙度、光照等）
• 🔄 自动旋转和轨道控制
• 💡 可调节的光照系统
• 🌅 多种预设环境
• 📱 响应式设计，自适应窗口大小
• 🏗️ 白模/材质模式切换
• 📊 加载进度显示
• 🔧 完整的API接口

安装

npm install vue-3d-model-viewer
# 或
yarn add vue-3d-model-viewer

快速开始

方式一：全局注册

import { createApp } from 'vue'
import App from './App.vue'
import ThreeModelViewer from 'vue-3d-model-viewer'
import 'vue-3d-model-viewer/dist/style.css'

const app = createApp(App)
app.use(ThreeModelViewer)
app.mount('#app')

方式二：局部导入

<template>
  <div class="model-viewer-wrapper">
    <ThreeModelViewer 
      :model-url="modelUrl"
      :auto-rotate="true"
      :light-intensity="1.2"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { ThreeModelViewer } from 'vue-3d-model-viewer'
import 'vue-3d-model-viewer/dist/style.css'

const modelUrl = ref('https://threejs.org/examples/models/gltf/DamagedHelmet/glTF/DamagedHelmet.gltf')
</script>

<style scoped>
.model-viewer-wrapper {
  width: 100%;
  height: 600px;
}
</style>

组件属性 (Props)

属性名	类型	默认值	说明
modelUrl	string	''	3D模型的URL路径，支持GLTF/GLB格式
autoRotate	boolean	false	是否启用模型自动旋转
rotationSpeed	number	0.01	自动旋转速度
lightAngle	number	45	主光源角度（度）
lightIntensity	number	1.5	主光源强度
metalness	number	0.3	模型金属度（0-1）
roughness	number	0.5	模型粗糙度（0-1）
showWhiteModel	boolean	false	是否显示为白模模式
environment	string	'default'	环境预设名称

暴露的API方法

组件通过 defineExpose 暴露以下方法，可通过组件引用调用：

方法名	参数	返回值	说明
resetView	无	void	重置视图到初始状态
resetLight	无	void	重置光照到初始设置
changeEnvironment	envName: string	void	切换环境预设
loadModel	url: string	void	加载指定URL的模型
getModel	无	THREE.Group | null	获取当前加载的模型对象
getScene	无	THREE.Scene	获取Three.js场景对象
getCamera	无	THREE.PerspectiveCamera	获取相机对象
getRenderer	无	THREE.WebGLRenderer	获取渲染器对象

API使用示例

<template>
  <div>
    <div class="model-viewer-wrapper">
      <ThreeModelViewer 
        ref="viewerRef"
        :model-url="modelUrl"
      />
    </div>
    <div class="controls">
      <button @click="resetModelView">重置视图</button>
      <button @click="changeToSunsetEnv">日落环境</button>
      <button @click="loadNewModel">加载新模型</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { ThreeModelViewer } from 'vue-3d-model-viewer'

const viewerRef = ref(null)
const modelUrl = ref('https://threejs.org/examples/models/gltf/DamagedHelmet/glTF/DamagedHelmet.gltf')

// 重置视图
const resetModelView = () => {
  if (viewerRef.value) {
    viewerRef.value.resetView()
  }
}

// 切换到日落环境
const changeToSunsetEnv = () => {
  if (viewerRef.value) {
    viewerRef.value.changeEnvironment('sunset')
  }
}

// 加载新模型
const loadNewModel = () => {
  if (viewerRef.value) {
    viewerRef.value.loadModel('https://threejs.org/examples/models/gltf/FlightHelmet/glTF/FlightHelmet.gltf')
  }
}

// 组件挂载后可以访问更多API
onMounted(() => {
  console.log('查看器已挂载')
  // 获取Three.js对象进行高级操作
  const scene = viewerRef.value?.getScene()
  const camera = viewerRef.value?.getCamera()
  
  // 示例：添加一个自定义光源
  if (scene) {
    // 这里可以进行更复杂的Three.js场景操作
  }
})
</script>

<style scoped>
.model-viewer-wrapper {
  width: 100%;
  height: 600px;
  position: relative;
}

.controls {
  display: flex;
  gap: 10px;
  padding: 20px;
}

button {
  padding: 8px 16px;
  background-color: #4a90e2;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

环境预设

组件内置了多种环境预设：

预设名称	说明
default	默认环境，明亮的中性色调
sunset	日落环境，暖色调
night	夜间环境，深蓝色调
blue	蓝色环境，冷色调

常见问题

模型不显示

• 确保提供正确的模型URL路径
• 检查模型格式是否为GLTF/GLB
• 为组件容器提供足够的尺寸（宽度和高度）
• 检查控制台是否有加载错误

性能优化建议

• 使用简化后的模型（LOD技术）
• 减少模型面数
• 优化材质和纹理
• 对于大型场景，考虑使用视锥剔除

移动端适配

组件已内置响应式设计，会自动适应窗口大小。在移动设备上，建议：

• 降低模型复杂度
• 减少光源数量
• 关闭不必要的后处理效果

浏览器兼容性

支持所有现代浏览器：

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

开发和构建

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建库
npm run build

许可证

MIT License

鸣谢

本组件基于Three.js开发，感谢Three.js社区的贡献。