# Threejs流光全栈底座

**Repository Path**: xiefan2333/VueAndThreejsByCodeXr

## Basic Information

- **Project Name**: Threejs流光全栈底座
- **Description**: 本项目是一个基于 Vue3 + Three.js 的 3D 前后端 全栈创作底座
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: threejs流光底座-前端版本-创世1.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2026-03-14
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3 + Three.js 封装包 - 前端底座

## 项目简介

本项目是一个基于 Vue3 + Three.js 的前端 3D 可视化解决方案，提供了完整的 3D 场景管理、模型加载、相机控制和渲染优化功能。项目采用模块化设计，支持多种开发模式，满足不同场景的需求。

## 技术栈

- **前端框架**：Vue 3 (Composition API)
- **3D 引擎**：Three.js
- **状态管理**：Pinia
- **路由管理**：Vue Router
- **UI 组件**：Element Plus
- **样式预处理**：Less
- **构建工具**：Vite
- **代码高亮**：Highlight.js
- **HTTP 客户端**：Axios

## 项目结构

```
VueAndThreejsByCodeXr/
├── public/
│   ├── threejs/              # Three.js 相关资源
│   │   ├── draco/            # DRACO 压缩解码器
│   │   ├── img/              # 环境贴图等图片资源
│   │   └── model/            # 3D 模型文件
├── src/
│   ├── assets/               # 静态资源
│   ├── components/           # 组件
│   │   └── common/threejs/   # Three.js 相关组件
│   │       ├── int/          # 核心封装类
│   │       └── single/       # 聚合性开发模式
│   ├── router/               # 路由配置
│   ├── views/                # 页面
│   │   ├── Introduction/     # 介绍页面
│   │   ├── index/            # 首页
│   │   ├── media/            # 媒体资源
│   │   ├── tool/             # 工具脚本
│   │   └── work/             # 项目工作区
│   ├── App.vue               # 根组件
│   ├── main.js               # 应用入口
│   └── style.css             # 全局样式
```

## 核心功能

### 1. 两种开发模式

- **离散性开发**：配置文件和组件分离，适合复杂场景和深度定制
- **聚合性开发**：单标签快速生成完整 3D 场景，适合快速原型开发

### 2. 模型加载与管理

- 支持 GLB 模型加载
- 实时显示加载进度
- 自动处理模型材质和光照
- 支持 DRACO 压缩减少模型加载时间

### 3. 相机控制

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

### 4. 渲染优化

- 支持曝光度调整
- 支持多种色调映射模式
- 自动处理环境贴图
- 性能优化和内存管理

### 5. 交互功能

- 模型点击交互
- 鼠标事件处理
- 场景状态管理

### 6. 项目管理

- 多项目工作区
- 项目配置保存和加载
- 相机调试工具
- 截图功能

## 快速开始

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

### 构建生产版本

```bash
npm run build
```

### 预览生产版本

```bash
npm run preview
```

## 开发模式

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

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

**使用示例**：

```vue
<!-- views/work/project/1/projectScene.vue -->
<template>
  <div class="project-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>
```

### 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>
```

## 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. **错误处理**：
   - 确保模型文件路径正确
   - 处理网络请求失败的情况
   - 添加适当的加载状态和错误提示

4. **项目管理**：
   - 使用工作区管理多个项目
   - 保存相机位置和场景配置
   - 利用截图功能记录场景状态

## 示例场景

### 1. 无人机展示

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

### 2. 产品展示

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

### 3. 项目工作区

- 多项目管理
- 相机调试工具
- 场景配置保存和加载

## 部署指南

1. **构建生产版本**：
   ```bash
   npm run build
   ```

2. **部署到服务器**：
   - 将 `dist` 目录上传到服务器
   - 配置服务器静态文件服务
   - 确保服务器支持现代 JavaScript 特性

3. **CDN 配置**：
   - 对于大型模型和资源，建议使用 CDN 加速
   - 配置适当的缓存策略

## 总结

本封装包提供了完整的 Vue3 + Three.js 前端 3D 解决方案，通过灵活的开发模式和丰富的功能，满足不同场景的需求：

- **离散性开发**：适合需要深度定制和复杂逻辑的场景
- **聚合性开发**：适合快速原型开发和简单场景
- **项目管理**：支持多项目工作区和配置管理
- **性能优化**：提供多种渲染优化和内存管理功能

通过合理使用本封装包，可以显著提高 3D 场景的开发效率和代码可维护性，为前端 3D 应用开发提供强大的基础支持。