# 仓库货位3D - Vue3 + Element Plus 版本

**Repository Path**: libcew/warehouse3d

## Basic Information

- **Project Name**: 仓库货位3D - Vue3 + Element Plus 版本
- **Description**: 仓库货位3D - Vue3 + Element Plus 版本，warehouse layout AI完善版，Claude Code+gm5.2生产
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 仓库3D - Vue3 + Element Plus 版本

仓库3D 是基于Three.js 的 Vue 3 组件化版本，可直接运行，也可作为独立组件集成到现有 Element Plus 项目。支持多库区切换、货位编码显示、平移阻尼等交互。

## 运行效果图

![运行效果图1](demo/screenshot_01.png)
![运行效果图2](demo/screenshot_02.png)

## 技术栈

- Vue 3 (`<script setup>`)
- Element Plus 2.7+（Tabs / Dialog / Switch / Checkbox / Table / Tooltip）
- Three.js 0.127.0（InstancedMesh 实例化渲染，npm 依赖，无外网/CDN 依赖）
- Vite 5 构建（内置 HMR 热加载）

## 目录结构

```
仓库3d-vue/
├── index.html                  # Vite 入口
├── package.json
├── vite.config.js              # Vite 配置(HMR/代理/别名)
├── README.md
├── DEVELOPMENT.md             # 开发指南(HMR 原理/调试/排查)
├── .env.development           # 开发环境变量
├── .env.production            # 生产环境变量
├── .gitignore
└── src/
    ├── main.js                 # 注册 Element Plus + HMR 调试
    ├── App.vue                 # Demo 外壳(全屏)
    ├── components/
    │   ├── Warehouse3D.vue     # 核心组件(自包含)
    │   └── buildTestLanes.js   # 测试数据生成器 + 库区集合(真实项目用接口替换)
    ├── config/
    │   └── warehouse.js        # 所有可配置参数(COLORS/LAYOUT/CAMERA/...)
    └── utils/
        ├── textRenderer.js     # 中文文本 Canvas 纹理渲染(支持描边)
        └── hmr.js              # HMR 事件监听调试工具
```

## 直接运行

```bash
cd 仓库3d-vue
npm install
npm run dev
```

浏览器打开 http://localhost:5173 （端口被占用时自动切换）。修改任意 `.vue` / `.js` 文件自动热更新。

打包预览：`npm run build && npm run preview`

## 集成到现有 Vue3 + Element Plus 项目

把以下文件/目录整体拷进你的项目（保持相对路径）：

```
src/components/Warehouse3D.vue
src/components/buildTestLanes.js
src/config/warehouse.js
src/utils/textRenderer.js
```

在你的页面中使用：

```vue
<template>
  <div style="width: 100%; height: 600px">
    <Warehouse3D :lanes="lanesFromApi" />
  </div>
</template>

<script setup>
import { ref, onMounted } from "vue";
import Warehouse3D from "@/components/Warehouse3D.vue";

const lanesFromApi = ref([]);
onMounted(async () => {
  // 真实项目:从接口拉取 lanes 数据(按库区 id 拉取对应货位)
  // lanesFromApi.value = await fetch("/api/warehouse/lanes?zoneId=zone1").then(r => r.json());
});
</script>
```

前提：你的项目已全局注册或按需引入 Element Plus（`el-tabs` / `el-dialog` / `el-switch` / `el-checkbox` / `el-table` / `el-tooltip` 等）。本 Demo 工程在 `main.js` 用 `app.use(ElementPlus)` 全量注册；现有项目若用 `unplugin-vue-components` 自动按需引入，无需额外配置。

## 组件 API

### Props

| 名称    | 类型   | 默认值              | 说明                                    |
| ------- | ------ | ------------------- | --------------------------------------- |
| `lanes` | Array  | `buildTestLanes()`  | 货位数据。真实项目用接口数据覆盖。      |

### 暴露方法（defineExpose）

| 名称              | 说明                         |
| ----------------- | ---------------------------- |
| `resetView()`     | 回到初始视图                  |
| `panView(dx, dy)` | 沿当前视角平移(带阻尼平滑)    |
| `refreshAllColors()` | 重新刷新货位配色           |

### 数据结构（lanes）

```js
[
  {
    lane: "1",                      // 巷道号
    zoneId: "zone1",                // 所属库区 id(与 WAREHOUSE_ZONES 对应)
    columns: [
      {
        column: "AA",               // 列号
        racks: [
          {
            floor: 4,               // 层数(决定该行渲染多少格)
            row: "AAA",             // 行号
            items: [                // 商品(空数组=空货位)
              { name: "可乐", spec: "330ml", qty: 10, unit: "盒" }
            ]
          }
        ]
      }
    ]
  }
]
```

货位编码格式：`CHR-{列号}-{行号}-{层号}`（如 `CHR-AA-AAA-1`）。

## 功能

- InstancedMesh 实例化渲染（5000+ 货位仍 ~15 draw calls、60fps）
- **多库区切换**：右上角选项卡切换库区，重载货位并重建 3D 场景，带加载动画
- 货位编码显示开关：开启后每个货位面向巷道通道一侧显示编码，**第一列/最后一列背面也额外显示**
- 中文文本渲染：Canvas 纹理方案（白底深色描边，任意底色都清晰）
- 鼠标悬停高亮 + 货位号/商品 tooltip
- **双击货位**弹窗显示明细（Element Plus Dialog + Table）
- 巷道筛选高亮（Checkbox）
- 右下角方向控制（按当前视角地面平移）+ 复位，**平移带阻尼平滑滑动**
- 右下角帮助图标，悬停显示鼠标操作说明
- 小库区自适应取景：货位少时自动采用更陡俯仰角 + 更高视点，便于俯瞰全貌
- 初始相机自适应取景（基于货位包围盒）
- 组件卸载时自动释放 Three.js 资源

### 鼠标操作

| 操作 | 功能 |
| ---- | ---- |
| 左键拖动 | 旋转视角 |
| 右键拖动 | 平移视角 |
| 滚轮 | 缩放远近 |
| 双击货位 | 查看货位详情 |
| 悬停货位 | 显示货位信息 |

## 配置

所有可调参数集中在 `src/config/warehouse.js`：

- `COLORS` — 场景配色（背景/地面/货位四态/线框/网格/文字）
- `LAYOUT` — 货位几何尺寸与间距
- `LIGHTING` — 半球光/环境光/平行光及阴影
- `FOG` — 雾效近远端
- `CAMERA` — 视野裁面 + 初始取景参数（`framing` 普通库区 / `smallZoneFraming` 小库区）
- `RENDER` — 抗锯齿/曝光
- `CONTROLS` — 轨道控制器交互开关与速度
- `PAN` — 方向面板平移步长 `step` + 阻尼系数 `damping`

库区集合在 `src/components/buildTestLanes.js` 的 `WAREHOUSE_ZONES`，各库区货位规模在 `ZONE_OVERRIDES`。从接口拉取配置后覆盖对应对象即可。