一、为什么要做这个项目?
在家庭装修规划和智能家居(尤其是 Home Assistant)折腾过程中,我发现市面上的工具存在一个明显的断层:
- 传统家装软件太重 / 商业化绑定深:AutoCAD、SketchUp 对普通人门槛过高;商业云端装修工具虽然上手快,但往往存在生态封闭、导出模型或高清图纸收费、数据无法完全私有化的问题。
- 传统 HA 3D 平面图维护成本极高:在 Home Assistant 社区中,流行的 Floorplan 方案通常是先在 SweetHome3D 或 Blender 里建好模、把每种灯的亮灭状态渲染成多张 PNG,再通过 CSS 图层叠加实现开关灯。一旦家里换了个灯、挪了张沙发,或者想看不同色温/RGB 的光影效果,就得重新渲染整套图片,既不实时,也无法自由旋转视角。
因此,我打造了现在的 HA3D 智慧户型 —— 一个**纯前端运行、零后端依赖、同时服务于“装修平面规划”与“Home Assistant 3D 实时可视化”**的开源 Web 应用。
二、核心功能全景介绍
1. 精密高效的 2D 户型编辑器
在最新版中,我们将 2D 渲染引擎全面升级为基于 requestAnimationFrame 的 Canvas 2D 高帧率引擎,并引入了节点-墙体-洞口拓扑数据模型(TopoGraph),解决了传统独立矩形墙体容易脱节错位的问题:
- 底图上传与比例尺标定:支持上传开发商户型图作为半透明底图,只需在图上两点标定并输入真实毫米长度(如门宽
900mm),即可自动缩放到 1:1 比例进行描摹。 - 智能绘图与联动编辑:
- 支持单段画墙、拆改墙体以及
B键快速拉矩形房间(支持绘制时直接键盘输入宽,深回车精确成型)。 - 拖动墙体平移或拖拽墙角端点时,相连垂直墙体与附着的门窗会自动跟随伸缩闭合,配合绿色中心线对齐参考线,绘图手感极佳。
- 选中平开门时支持画布内一键「翻转」开门朝向与合页方向;门窗可直接在墙体间拖拽换墙。
- 支持单段画墙、拆改墙体以及
- 画布内“所见即所得”改数:无需频繁切换右侧属性面板,直接点击画布上的蓝色尺寸数字即可原地修改墙长、门窗宽度、门窗距墙角距离以及家具到四周墙体的离墙距离。
- 家具库与自动算量:内置卧室、客厅、灯具、餐厨、卫浴、家电、书房·休闲 7 大类常用家具,支持 8 点拖拽缩放、贴墙自动吸附(按住
Alt临时取消吸附)。系统会自动识别封闭房间、计算套内使用面积,并支持为每个房间切换地面材料(木地板、地砖、大理石、水磨石、地毯等),按 实际面积 + 5% 损耗 估算材料造价。
2. Three.js 3D 实时场景与第一人称漫游
按下 T 键即可从 2D 无缝切换至 Three.js(r160)构建的 3D 场景:
- 纯代码程序化建模:家具模型(包含柜门分缝、金属拉手、软包床头、陶瓷与金属环境反射材质等)全部通过 TypeScript + Three.js 代码程序化生成,无需请求动辄数十 MB 的外部模型资源包,首屏加载极快。项目还内置了独立的
/models模型展厅页面,方便开发者预览和调试各类扩展模型。 - 双风格 3D 视图与昼夜光影:
- 提供常规 3D 视图与 HA3D 毛玻璃薄墙视图(半透明磨砂墙体,更适合作为智能家居中控大屏底图)。
- 支持全高墙 / 剖切墙切换、日照时间滑块(模拟全天候太阳角度与夜景灯光)、以及可选的“墙体灯光遮挡”开关。
- 第一人称漫游(PC + 移动端适配):PC 端支持
WASD+ 鼠标锁定漫游,移动端/平板支持屏幕虚拟摇杆;靠近门扇时可点击或按E键实时开关门。此外,在 3D 场景中也可以直接选中并拖动家具,改动实时回写 2D 方案。
3. Home Assistant 实时双向联动与环境看板
这是 HA3D 区别于普通户型工具的核心能力:
- WebSocket 原生直连:直接在浏览器中通过 WebSocket 连接内网或公网的 Home Assistant(
ws://<IP>:8123/api/websocket),使用 Long-Lived Access Token 鉴权,配置持久化在本地localStorage中。 - 实体绑定与实时同步:将户型中的灯具与 HA 的
light.*实体绑定后,支持 开/关状态、亮度(Brightness)、色温(Kelvin/Mired)与 RGB 色彩 的双向实时同步。无论是点击 3D 场景里的灯具,还是外部触发自动化,画面都会即时响应。 - HA 环境感知看板:界面内置了精美的环境数据面板(包含时间/农历问候、室内温湿度、PM2.5、空调/新风/窗帘状态卡片与趋势折线图),配合 HA3D 夜景视图,非常适合直接全屏投放在家里的中控平板上。
4. 数据安全与多格式导出
- 纯前端静态部署:项目基于 Next.js
output: 'export'配置,构建产物为纯静态 HTML/JS/CSS(out/目录),无需 Node.js 后端即可部署到 NAS(群晖/威联通/飞牛等)、Nginx、Vercel 或 GitHub Pages。 - 开放的数据导入导出:支持一键导出高清 PNG 图像、JSON 完整方案备份与导入,还支持 直接导出标准
.glb格式的 3D 场景模型,方便导入 Blender 等专业工具进行后续渲染。
三、技术栈与架构简析(面向开发者)
对于想二次开发或学习 Three.js / Canvas 编辑器架构的同学,本项目也是一个非常干净的工程参考:
- 前端框架:Next.js 16(Pages Router + 静态导出)+ React 19 + TypeScript 5 + Tailwind CSS v4
- 2D 引擎(
lib/canvas2d.ts、lib/topo.ts、lib/rooms.ts):- 将原先的 SVG DOM 渲染重构为 Canvas 2D
requestAnimationFrame渲染管线,支持高 DPI 自适应与几何热区命中检测(hitTestCanvas)。 - 通过
rectsToTopo/topoToRects实现矩形墙体与拓扑图模型的双向同步,配合射线法/多边形环路搜索自动识别封闭房间。
- 将原先的 SVG DOM 渲染重构为 Canvas 2D
- 3D 引擎(
lib/render3d.ts、lib/models/):- 采用动态导入按需初始化 Three.js,使用
OrbitControls、PointerLockControls、RoomEnvironment与GLTFExporter。 - 家具模型按空间模块化拆分(
bedroom.ts、living.ts、kitchenBath.ts、lights.ts、openings.ts、studyMisc.ts等),结构清晰,易于扩展自定义家具。
- 采用动态导入按需初始化 Three.js,使用
- HA 通信层(
lib/ha.ts):- 封装了完整的 HA WebSocket 心跳、重连、状态订阅与服务调用(
call_service),无任何中间代理服务器。
- 封装了完整的 HA WebSocket 心跳、重连、状态订阅与服务调用(
四、5 分钟本地运行与部署教程
本地开发与运行
# 1. 安装依赖
npm install
# 2. 启动开发服务器(访问 http://localhost:3000)
npm run dev
静态构建(部署到 NAS / Nginx / 静态托管)
npm run build
构建完成后,项目根目录下的 out/ 文件夹即为完整的纯静态网站,直接将其放入任意 Web 服务器的根目录即可访问。
关于 Home Assistant 跨域/混合内容提示:如果 HA3D 部署在 HTTPS 域名下,浏览器可能会拦截
ws://非加密连接,建议将 HA 配置为wss://(通过反向代理开启 HTTPS),或在局域网内直接通过 HTTP 访问本地部署的 HA3D 站点。
