# dxf-view

**Repository Path**: yzdel2000/dxf-view

## Basic Information

- **Project Name**: dxf-view
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DXF 在线预览（dxf-view）

基于 **Vue 3 + TypeScript + Vite** 的浏览器端 DXF 文件预览工具，借助 [`three-dxf-viewer`](https://www.npmjs.com/package/three-dxf-viewer) 与 [three.js](https://threejs.org/) 在 WebGL 中渲染 AutoCAD 的 DXF 图形文件，无需安装任何 CAD 软件，浏览器打开即可查看。

应用启动后提供 **2D 正交预览**,适合工程图阅读。

> ℹ️ 3D 透视预览曾在早期版本提供,后因 `three-dxf-viewer` 对 3D 实体支持不足被暂时移除,仅保留 2D 模式。

![tech](https://img.shields.io/badge/Vue-3.5-42b883) ![tech](https://img.shields.io/badge/TypeScript-6-3178c6) ![tech](https://img.shields.io/badge/Vite-8-646cff) ![tech](https://img.shields.io/badge/three.js-0.171-000000) ![tech](https://img.shields.io/badge/three--dxf--viewer-1.0.44-orange)

---

## ✨ 功能特性

- 🏠 **模式选择首页**:进入应用后从首页卡片进入 2D 预览(后续扩展更多模式时将在此并列展示)。
- 📐 **2D 正交预览**:使用 `OrthographicCamera`,禁用旋转,仅支持平移与缩放,符合工程图阅读习惯。
- 📂 **本地加载**:通过文件选择对话框加载本地 `.dxf` 文件,解析并即时渲染。
- 🔍 **自动取景**:加载完成后根据模型 XY 包围盒与画布宽高比计算 uniform frustum,含 1.4× padding,确保图形完整居中。
- 📐 **响应式画布**:通过 `ResizeObserver` 监听容器尺寸变化,保持 Y 方向可见范围不变,按新宽高比调整 X 方向 frustum。
- 🧹 **资源释放**:切换文件前清理上一份几何体和材质,避免 GPU 内存泄漏;组件卸载时统一释放 renderer、controls、canvas 节点。
- ⏳ **状态提示**:顶栏实时显示加载状态(空闲 / 解析中 / 已加载 / 失败原因)。
- 🔠 **中文字体**:内置 `FangSong_Regular.json`(仿宋体 typeface),保证 DXF 中的中文及常规字符正常显示。

---

## 🛠️ 技术栈

| 类别        | 选型                                                       |
| ----------- | ---------------------------------------------------------- |
| 框架        | Vue 3 (`<script setup>` SFC)                               |
| 语言        | TypeScript                                                 |
| 构建工具    | Vite                                                       |
| 3D 渲染     | three.js                                                   |
| DXF 解析    | three-dxf-viewer                                           |
| 包管理器    | pnpm                                                       |
| 字体        | `FangSong_Regular.json`(仿宋体 typeface,支持中文)         |

---

## 📁 目录结构

```
dxf-view/
├── public/                          # 静态资源(构建后会原样拷贝到 dist)
│   ├── favicon.svg
│   ├── icons.svg
│   └── FangSong_Regular.json        # 仿宋体字体文件(DXF 文本渲染用,覆盖中文字形)
├── src/
│   ├── assets/                      # 图片等本地资源
│   │   ├── hero.png
│   │   ├── vite.svg
│   │   └── vue.svg
│   ├── components/                  # 业务组件
│   │   └── DXF2DPreview.vue         # 2D 正交预览(OrthographicCamera,禁用旋转)
│   ├── types/
│   │   └── three-dxf-viewer.d.ts    # 第三方库类型补充
│   ├── App.vue                      # 应用入口(首页 + 模式切换)
│   ├── main.ts                      # 应用挂载入口
│   └── style.css                    # 全局样式
├── index.html                       # HTML 入口
├── vite.config.ts                   # Vite 配置
├── tsconfig*.json                   # TypeScript 配置
├── package.json
└── README.md
```

---

## 🚀 快速开始

### 环境要求

- **Node.js** ≥ 20(推荐 LTS;`typescript ~6.0.2` 与 `vite ^8.0.12` 需要较新版本)
- **pnpm**(推荐,可使用 `npm` 或 `yarn` 替代)

### 安装依赖

```bash
# 推荐使用 pnpm
pnpm install

# 或使用 npm
npm install
```

### 启动开发服务器

```bash
pnpm dev
```

启动后访问终端输出的本地地址(默认为 <http://localhost:5173>)。

### 构建生产包

```bash
pnpm build
```

构建产物输出到 `dist/` 目录。

### 本地预览生产包

```bash
pnpm preview
```

---

## 📖 使用说明

1. 启动项目后,首页会显示 **「2D 预览」** 入口卡片。
2. 点击进入预览页,再点击右上角 **「加载」** 按钮选择 `.dxf` 文件。
3. 应用开始解析并渲染,顶栏会显示「正在解析:xxx.dxf」等状态。
4. 加载完成后,图形自动居中并适配窗口大小。
   - 鼠标左键 / 右键拖拽平移。
   - 滚轮缩放(`minZoom = 0.1`,`maxZoom = 100`)。
   - 旋转被禁用(2D 视图不需要)。
5. 想要切换文件,再次点击「加载」即可,旧的模型资源会被自动释放。
6. 点击顶栏 **「← 返回」** 可回到首页。

> 💡 再次选择同名文件时浏览器默认不会触发 `change` 事件,代码已在 `onFileChange` 末尾把 `input.value` 重置为 `""`,确保行为符合预期。

---

## 🧩 核心实现说明

### 1. 应用入口 `src/App.vue`

仅维护一个 `mode` 状态(`'home' | '2d'`),根据当前模式渲染首页卡片或 `DXF2DPreview` 组件。不包含任何 three.js 渲染逻辑,只做路由式切换。

### 2. 2D 预览 `src/components/DXF2DPreview.vue`

整个 three.js 渲染管线、文件加载、资源释放都集中在该单文件组件内:

- **场景搭建**(`onMounted`):创建 `THREE.Scene`(背景 `#1e1e22`)、`WebGLRenderer`(开启抗锯齿)、`OrthographicCamera`(初始范围按画布宽高,`near/far = ±10000`)、`OrbitControls`(damping 0.08)。仅添加 `AmbientLight`,方向光在俯视角度会造成迷惑性阴影。
- **2D 交互**:`OrbitControls.enableRotate = false`,左键 / 右键均映射为 `MOUSE.PAN`,滚轮缩放范围 `0.1 ~ 100`。
- **DXF 加载**(`loadFile`):调用 `viewer.getFromFile(file, FONT_URL)` 异步解析;成功后 `scene.add(dxf)` 并调用 `fitCameraToObject` 自适应取景;失败时把错误信息写入顶栏 `statusText`,不向用户抛错。
- **取景算法**(`fitCameraToObject`):用 `Box3` 计算包围盒,取 XY 最大维度 × 1.4 padding 作为 uniform frustum,按画布宽高比调整 X 方向,相机移到 `(centerX, centerY, 100)`,`OrbitControls.target` 同步到包围盒中心。空 DXF 会得到 `box.isEmpty()`,此时静默 return,相机保持上一次位置。
- **响应式画布**(`handleResize` + `ResizeObserver`):保持 Y 方向可见范围不变,按新宽高比重算 `left` / `right`。
- **资源释放**:
  - 切换文件前 `disposeCurrentDxf()` 遍历 `currentDxf`,逐个 `geometry.dispose()` / `material.dispose()`,并从场景移除。
  - `onBeforeUnmount` 取消 `requestAnimationFrame`、移除 `resize` 监听、断开 `ResizeObserver`、调用 `controls.dispose()` / `renderer.dispose()`,并把 canvas 从 DOM 移除、解引用全部实例。

> ℹ️ 设计上所有 three.js 实例都用 `let` + `null` 初始化、放在 `<script setup>` 闭包里而非 `ref`/`reactive`。响应式包装会引入不必要的追踪开销,且对 `.dispose()` 的命令式调用不友好。

### 3. 字体加载

`FONT_URL` 通过 `import.meta.env.BASE_URL` 拼接 `public/FangSong_Regular.json`,作为第二个参数传给 `viewer.getFromFile(file, FONT_URL)`。如需更换字体,只需替换 `public/` 下的 typeface JSON 并同步更新 `FONT_URL` 常量即可。

---

## 🐛 常见问题

**Q1:加载 DXF 后看不到任何东西?**
- 检查 DXF 文件本身是否完整,可以先用 AutoCAD 或其他工具打开确认。
- 打开浏览器控制台查看是否有报错信息。
- 如果文件较大或图形非常复杂,可能需要等待几秒。
- 若 DXF 为空(`box.isEmpty()`),取景会静默跳过,顶栏会显示「已加载」但画面无变化。

**Q2:文字显示为方块或乱码?**
- 默认使用 `FangSong_Regular.json`(仿宋体)字体。如出现个别生僻字仍为方块,可替换为覆盖更全字符集的 typeface 字体文件,并在 `DXF2DPreview.vue` 的 `FONT_URL` 中同步更新路径。

**Q3:构建或启动报错?**
- 确认 Node.js 版本符合要求(≥ 20)。
- 删除 `node_modules` 与锁文件后重新安装依赖。

**Q4:为什么不能旋转?**
- 这是预期行为:2D 预览刻意禁用旋转以避免误操作。

**Q5:为什么没有 3D 预览?**
- 项目早期曾包含 3D 透视预览组件,但 `three-dxf-viewer` 当前对 3D 实体(如 `3DSOLID`、`MESH`)的支持有限,渲染结果与 2D 几乎一致,因此暂时移除,后续视上游支持情况再恢复。

---

## 📜 脚本命令一览

| 命令            | 说明                       |
| --------------- | -------------------------- |
| `pnpm dev`      | 启动 Vite 开发服务器       |
| `pnpm build`    | `vue-tsc` 类型检查并构建   |
| `pnpm preview`  | 本地预览生产构建结果       |

---

## 📄 License

仅供学习与个人项目使用。`three-dxf-viewer` 与 `three.js` 遵循各自的 MIT 开源协议。