淋浴房方案绘图项目总结
文档日期: 2026-06-02
项目类型: 前端单页应用；面向淋浴房方案的参数化绘图工具
构建验证: 已执行 npm run build，Vite 生产构建成功
一句话概括
本项目实现了一个在浏览器中运行的淋浴房方案绘图工具：用户可以基于预设或空白方案调整尺寸、添加构件和边框，实时生成等轴透视线稿，并导出 SVG/PNG 供沟通和交付使用。
一、项目概况
项目名称为 shower-plan-drawing-app，页面标题为“淋浴房方案绘图”。项目采用纯前端实现，不依赖后端服务，主要用于快速生成淋浴房方案示意图、调整尺寸参数、对构件进行可视化编辑，并输出可保存或进一步编辑的图纸文件。
从业务定位看，它更像一个轻量级方案草图与沟通工具：不是完整 CAD 系统，但已经具备参数驱动、构件编辑、等轴投影、材料估算和图片导出的核心闭环。
二、技术栈与工具
| 层次 | 技术或工具 | 在项目中的作用 |
|---|---|---|
| 前端框架 | React 19.1、React DOM | 使用组件和 Hooks 管理页面、方案状态、选中对象、缩放和拖拽交互。 |
| 构建工具 | Vite 7、@vitejs/plugin-react | 提供本地开发、生产构建和 React 编译能力；配置 base: ./ 便于静态部署。 |
| 语言与模块 | JavaScript / JSX / ES Modules | 核心业务逻辑写在 src/main.jsx；依赖中包含 TypeScript，但当前业务源码不是 TS/TSX。 |
| 图形渲染 | SVG | 使用 viewBox、path、line、polygon、rect 等 SVG 元素绘制等轴透视图和可交互对象。 |
| 导出能力 | XMLSerializer、Blob、URL、Canvas API | 将 SVG 序列化为文件；PNG 导出时先把 SVG 绘制到 Canvas，再生成图片下载。 |
| 界面样式 | CSS Grid、Flexbox、媒体查询 | 实现顶部工具栏、画布区域、右侧检查器面板和移动端适配。 |
| 图标库 | lucide-react | 用于工具栏、面板标题、导出和缩放等 UI 图标。 |
| 静态封装 | Node.js fs/path 脚本 | scripts/build-static.cjs 会把构建后的 CSS/JS 内联到单个 HTML 文件。 |
三、已实现的主要功能
| 功能模块 | 说明 |
|---|---|
| 方案管理 | 内置“基础方案”“备用方案”等预设；支持新建空白方案、复制当前方案、切换方案和重命名导航标签。 |
| 尺寸参数编辑 | 可调整方案名称、正面宽、侧面深、高度、墙边距等核心参数；输入组件带最小值、最大值和提交校验。 |
| 等轴透视绘图 | 通过 makeGeometry 中的 p(x, y, z) 投影函数，将毫米单位的三维坐标映射为二维 SVG 坐标。 |
| 自定义构件 | 支持玻璃、墙体、拉手、合页四类构件；可编辑类型、平面、坐标、尺寸、角度和显示状态。 |
| 自定义边框 | 支持直线边框和弧形边框；可配置所在平面、长度、角度、半径、位置，并选择是否显示长度标注。 |
| 拖拽交互 | 用户可直接在 SVG 图上选中并拖动构件或边框；拖拽位移会根据对象所在平面转换回三维坐标。 |
| 缩放和纸张背景 | 工具栏提供放大/缩小；画布支持白底和浅灰底两种纸张效果。 |
| 导出能力 | 支持导出 SVG 和 PNG；SVG 导出会嵌入当前页面样式，PNG 使用 2 倍画布尺寸生成。 |
| 材料估算 | 右侧面板显示正面玻璃、侧面玻璃、轨道估长、自定义边框长度和玻璃面积估算。 |
| 响应式界面 | 桌面端采用画布 + 右侧检查器布局；窄屏下检查器自动移动到下方，画布可横向滚动。 |
四、核心实现结构
1. 数据模型
应用以 schemes 数组作为最外层状态，每个方案包含 id、name、presetKey 和 drawing。drawing 内部保存项目名称、尺寸参数、玻璃厚度、边框颜色，以及 customFrames 和 customParts 两组可编辑对象。
customParts 表示玻璃、墙体、拉手、合页等构件，字段包括 type、plane、x/y/z、w/d/h、angle、show。
customFrames 表示线性或弧形边框，字段包括 type、plane、x/y/z、length、angle、radius、showLabel。
预设方案通过 buildCustomFrames 和 buildCustomParts 自动生成默认框架、玻璃、墙垛、拉手和合页。
2. 渲染与交互分层
| 模块 | 职责 |
|---|---|
| App | 页面状态、方案管理、表单面板、导出逻辑和拖拽入口。 |
| IsoScheme | 创建等轴投影上下文，并组合构件层与边框层。 |
| CustomPartLayer / CustomPart | 按构件类型分发渲染玻璃面、立体墙体、拉手和合页。 |
| CustomFrameLayer / CustomFrame | 渲染直线/弧线边框、选中态、命中区域和长度标注。 |
| NumberField / Toggle / Panel | 复用表单控件，负责数值输入、开关和右侧面板结构。 |
3. 几何与投影逻辑
makeGeometry 会先对输入尺寸进行范围限制，再计算 x、y、z 三个方向的缩放比例。核心投影函数 p(x, y, z) 将三维坐标转换为 SVG 平面坐标，从而实现类似工程示意图的等轴透视效果。
拖拽时，dragDeltaFor 会根据对象所在平面分别处理 front、side、floor、box、angled 等场景，把屏幕上的 dx/dy 位移转换为对应的 x/y/z 坐标变化。这样构件在不同平面中拖动时仍能保持合理的空间关系。
五、运行与交付方式
| 用途 | 命令 | 说明 |
|---|---|---|
| 安装依赖 | npm install | 根据 package-lock.json 安装 Vite、React、lucide-react 等依赖。 |
| 本地开发 | npm run dev | 启动 Vite 开发服务器，默认绑定 127.0.0.1。 |
| 生产构建 | npm run build | 输出 dist/index.html、CSS 和 JS 资源。已验证构建成功。 |
| 本地预览 | npm run preview | 使用 Vite preview 预览生产构建结果。 |
| 单文件输出 | npm run build:static | 先构建，再生成 dist-static/淋浴房方案绘图.html，便于单文件分发。 |
本次检查已执行 npm run build，构建结果显示 1578 个模块转换完成，CSS 约 9.00 kB，JS 约 225.91 kB（gzip 约 70.72 kB）。
六、项目亮点
业务场景明确：围绕淋浴房方案沟通，把尺寸、玻璃、墙体、拉手、合页和边框编辑集中到一个页面中。
纯前端闭环完整：无需后端即可完成方案编辑、实时绘图、材料估算和图片导出。
图形实现较轻量：没有引入大型 CAD 或 3D 引擎，而是用 SVG 和自定义投影函数完成工程线稿表达。
交互成本低：右侧表单适合精确输入，画布拖拽适合快速调整，二者能同步更新同一份状态。
具备交付意识：支持 SVG 可编辑导出，也支持 PNG 图片交付；另有单 HTML 打包脚本。
七、当前不足与后续优化建议
项目目前没有持久化存储，刷新页面后方案会丢失；可增加 localStorage、JSON 导入/导出或云端保存。
导出的 SVG/PNG 是图形成果，但项目参数本身没有独立文件格式；可设计 .json 项目文件，方便二次编辑。
材料估算偏轻量，当前主要统计玻璃面积和边框长度；可加入五金、轨道、损耗、单价和报价清单。
代码集中在单个 main.jsx 中，后续功能增加后可拆分为 geometry、drawing-model、components、export 等模块。
当前 package.json 没有测试脚本；建议补充几何计算、投影转换、导出逻辑和关键组件的自动化测试。
可增加撤销/重做、对象复制、吸附对齐、图层管理、尺寸标注系统等更接近绘图软件的能力。
八、关键文件说明
| 文件 | 作用 |
|---|---|
| src/main.jsx | 应用主体：状态管理、方案数据模型、等轴绘图、拖拽交互、导出逻辑和表单控件。 |
| src/styles.css | 全局样式、页面布局、画布视觉、面板样式、选中态和响应式适配。 |
| package.json | 项目名称、依赖和 npm 脚本定义。 |
| vite.config.js | Vite 配置；使用 React 插件，并设置相对路径 base。 |
| scripts/build-static.cjs | 读取 dist 中的 HTML/CSS/JS，并生成单个可分发 HTML 文件。 |
| dist-static/淋浴房方案绘图.html | build:static 脚本生成的静态交付文件。 |
| assets/concept-shower-planner.png | 项目中的概念设计图资产，当前源码未直接引用。 |
总结
整体来看，这个项目已经完成了一个可运行、可交互、可导出的淋浴房方案绘图原型。它的核心价值在于把尺寸参数、空间构件和方案图输出放在同一个浏览器应用中，适合用于方案初稿、客户沟通和内部确认。后续如果继续迭代，优先建议补齐方案持久化、项目文件导入/导出、报价清单和自动化测试，让它从“方案绘图工具”逐步增强为更完整的轻量设计交付工具。