# 代码仙人Vue+threejs 开源包

**Repository Path**: SJZchina/VueAndThreejsByCodeXr

## Basic Information

- **Project Name**: 代码仙人Vue+threejs 开源包
- **Description**: 本项目是一个基于 Vue3 + Three.js 的 3D 场景封装包，提供了两种开发模式：离散性开发和聚合性开发。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3 + Three.js 封装包使用文档

## 项目架构

本项目是一个基于 Vue3 + Three.js 的 3D 场景封装包，提供了两种开发模式：离散性开发和聚合性开发。

### 目录结构

```
newVue3/
├── public/
│   ├── threejs/
│   │   ├── draco/           # DRACO 压缩解码器
│   │   ├── img/             # 环境贴图等图片资源
│   │   └── model/           # 3D 模型文件
├── src/
│   ├── components/
│   │   └── common/
│   │       └── threejs/
│   │           ├── int/      # 核心封装类
│   │           └── single/   # 聚合性开发模式
│   ├── views/
│   │   ├── demo/            # 示例页面
│   │   │   ├── Hello World/ # 离散性开发示例
│   │   │   └── single/      # 聚合性开发示例
│   ├── router/              # 路由配置
│   ├── main.js              # 应用入口
│   └── App.vue              # 根组件
```

## 开发模式

### 1. 离散性开发模式

**特点**：
- 配置文件和组件分离，更灵活可控
- 适合复杂场景和需要深度定制的项目
- 每个功能模块可单独修改和扩展

**使用示例**：

```vue
<!-- views/demo/Hello World/droneScene.vue -->
<template>
  <div class="drone-scene">
    <div ref="threejsDom" class="threejs-dom"></div>
    <Loading :loadingProgress="loadingProgress" :modelLoading="modelLoading" />
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { createScene } from './createScene'
import Loading from './loading.vue'

const threejsDom = ref(null)
const loadingProgress = ref(0)
const modelLoading = ref(true)
let scene = null

onMounted(async () => {
  scene = await createScene(threejsDom.value, loadingProgress, modelLoading)
})

onUnmounted(() => {
  if (scene) {
    scene.destroy()
  }
})
</script>
```

**核心文件**：
- `createScene.js` - 场景创建和初始化逻辑
- `loading.vue` - 加载进度组件
- 可根据需要修改任何部分

### 2. 聚合性开发模式

**特点**：
- 单标签快速生成完整 3D 场景
- 传入参数即可配置，使用简单
- 适合快速原型开发和简单场景

**使用示例**：

```vue
<template>
  <SingleScene 
    ref="singleSceneRef" 
    :modelPath="'threejs/model/凤梨雪糕1.glb'"
    :cameraPosition="{ x: -120.97, y: -10.58, z: 286.01 }"
    storeId="productShowcase"
    :isCameraTest="false"
    :exposure="0.1"
    @ready="onReady"
    @cameraReady="onCameraReady"
  />
</template>

<script setup>
import { ref } from 'vue'
import SingleScene from '@/components/common/threejs/single/SingleScene.vue'

const singleSceneRef = ref(null)

const onReady = (scene) => {
  console.log('Single场景初始化完成', scene)
}

const onCameraReady = (camera) => {
  console.log('相机准备就绪', camera)
}
</script>
```

**核心文件**：
- `SingleScene.vue` - 聚合性场景组件
- `singleScene.js` - 场景逻辑封装
- `Loading.vue` - 加载进度组件

## 核心功能

### 1. 模型加载与进度显示

- 支持 GLB 模型加载
- 实时显示加载进度
- 自动处理模型材质和光照

### 2. 相机控制

- 支持轨道控制器
- 可自定义相机位置
- 提供相机测试模式

### 3. 渲染设置

- 支持曝光度调整
- 支持多种色调映射模式
- 自动处理环境贴图

### 4. 状态管理

- 使用 Pinia 管理场景状态
- 组件销毁时自动重置状态
- 支持多场景独立状态管理

## API 参考

### SingleScene 组件

**属性**：
- `modelPath` - 模型文件路径（必填）
- `cameraPosition` - 相机位置，默认 `{ x: 0, y: 0, z: 10 }`
- `storeId` - 状态管理ID，默认 `'singleScene'`
- `width` - 场景宽度，默认 `'100%'`
- `height` - 场景高度，默认 `'80vh'`
- `backgroundColor` - 背景颜色，默认 `'black'`
- `isCameraTest` - 是否启用相机位置测试，默认 `false`
- `exposure` - 曝光度，默认 `1.0`

**事件**：
- `ready` - 场景初始化完成
- `cameraReady` - 相机准备就绪

**方法**：
- `getScene()` - 获取场景实例
- `getStore()` - 获取状态管理实例
- `getCamera()` - 获取相机实例

### 离散性开发 API

**createScene 函数**：
- 参数：
  - `dom` - 渲染容器
  - `loadingProgress` - 加载进度引用
  - `modelLoading` - 加载状态引用
- 返回：场景实例，包含 `destroy()` 方法

## 最佳实践

1. **选择合适的开发模式**：
   - 简单场景使用聚合性开发模式
   - 复杂场景使用离散性开发模式

2. **性能优化**：
   - 合理设置相机位置和视角
   - 优化模型文件大小
   - 使用 DRACO 压缩减少模型加载时间

3. **错误处理**：
   - 确保模型文件路径正确
   - 处理网络请求失败的情况
   - 组件销毁时正确清理资源

## 示例场景

### 1. 无人机展示

- 使用离散性开发模式
- 展示复杂的 3D 模型
- 包含自定义加载逻辑

### 2. 产品展示

- 使用聚合性开发模式
- 快速创建产品展示场景
- 支持曝光度调整

## 总结

本封装包提供了两种灵活的开发模式，满足不同场景的需求：

- **离散性开发**：适合需要深度定制和复杂逻辑的场景
- **聚合性开发**：适合快速原型开发和简单场景

通过合理选择开发模式，可以显著提高 3D 场景的开发效率和代码可维护性。