# IoT 可视化编辑器 TODO
## 目标
基于 webbuilder.js 改造，实现支持网格布局的 IoT 可视化编辑器。
## 技术方案
- **布局方式**：CSS Grid 网格布局（24列）
- **单元格比例**：1:1（正方形）
- **画布尺寸**：固定手机宽度（375px），高度自适应
- **存储格式**：JSONB，预留多端接口（phone/computer）
- **前端技术栈**：纯 HTML + CSS + JavaScript（禁止 npm）
---
## 一、核心框架修改
### 1.1 webbuilder.js 主模块
- [x] 初始化时接收容器元素（div）
- [x] 移除组件类型限制（element/container）
- [x] 添加画布配置（列数、行高、间距）
- [x] 添加 `getCanvasConfig()` 方法
- [x] 添加 `setCanvasConfig(config)` 方法
- [x] 添加 `toJSONB()` 方法 - 导出为 JSONB
- [x] 添加 `fromJSONB(jsonb)` 方法 - 从 JSONB 加载
- [x] 添加 `toHTML()` 方法 - 生成 HTML 代码
### 1.2 Component.js 组件类
- [x] 添加 `id` 属性（唯一标识）
- [x] 添加 `props` 属性（组件自定义属性）
- [x] 添加 `style` 属性（组件样式）
- [x] 添加 `gridPosition` 属性（网格位置）
```javascript
gridPosition: {
column: 1, // 起始列
row: 1, // 起始行
columnSpan: 3, // 跨列数
rowSpan: 2 // 跨行数
}
```
- [x] 添加 `toJSONB()` 方法
- [x] 添加 `fromJSONB(jsonb)` 静态方法
- [x] 添加 `toHTML()` 方法
### 1.3 BuilderContainer.js 容器类
- [x] 修改为 Grid 容器
- [x] 添加网格配置（columns、rowHeight、gap）
- [x] 修改拖放逻辑：计算目标行列位置
- [x] 添加组件拖拽移动功能（在画布内移动）
- [x] 添加组件选中/取消选中功能
- [x] 添加组件删除功能
- [ ] 添加网格辅助线显示
### 1.4 BuilderToolbox.js 工具箱类
- [x] 添加组件分类支持
- [x] 添加组件预览图标
- [ ] 添加搜索/过滤功能
- [ ] 按分类组织：数据展示类、控制输入类、布局容器类
---
## 二、编辑器功能
### 2.1 画布编辑
- [x] 画布尺寸配置（支持手机/电脑端预览切换）
- [x] 手机端：375x812，24列网格
- [x] 电脑端：1200x800，24列网格
- [ ] 网格线显示/隐藏
- [x] 组件吸附到网格
- [x] 组件拖拽调整位置
- [ ] 组件拖拽调整大小（跨列/跨行）
- [ ] 组件右键菜单（删除、复制、置顶/置底）
### 2.2 组件选中
- [x] 点击选中组件
- [x] 选中高亮边框
- [ ] 显示调整大小手柄
- [x] 点击空白处取消选中
### 2.3 属性面板
- [x] 选中组件时显示属性面板
- [x] 显示组件基础属性（位置、大小）
- [x] 显示组件自定义属性
- [x] 实时更新组件
### 2.4 工具栏
- [x] 保存按钮
- [x] 预览按钮
- [ ] 撤销/重做按钮（可选）
- [x] 清空画布按钮
---
## 三、JSONB 存储结构
### 3.1 输出格式
```json
{
"version": "1.0",
"layouts": {
"phone": {
"canvas": {
"width": 375,
"height": 812,
"columns": 24,
"rowHeight": 30,
"gap": 8,
"background": "#f5f5f5"
},
"components": [
{
"id": "gauge-001",
"type": "gauge",
"grid": {
"startCell": 0,
"colSpan": 6,
"rowSpan": 6
},
"props": {
"label": "温度",
"value": 25,
"unit": "°C"
}
}
]
},
"computer": null
}
}
```
### 3.2 加载功能
- [x] 从 JSONB 恢复画布配置
- [x] 从 JSONB 恢复所有组件
- [x] 从 JSONB 恢复组件位置和属性
---
## 四、HTML 生成
### 4.1 生成规则
- [x] 根据 JSONB 生成完整的 HTML 结构
- [x] 生成内联 CSS 样式
- [ ] 生成组件初始化脚本
### 4.2 输出格式
```html
```
---
## 五、组件接口规范
框架不实现具体组件，只提供接口规范，使用者按规范自定义组件。
### 5.1 组件注册接口
```javascript
// 注册自定义组件
webbuilder.define('my-component', {
// 组件唯一标识
type: 'my-component',
// 默认属性
defaultProps: {
label: '默认文本',
value: 0
},
// 属性定义（用于属性面板）
traits: [
{ type: 'text', name: 'label', label: '标签' },
{ type: 'number', name: 'value', label: '值' },
{ type: 'device-selector', name: 'deviceId', label: '绑定设备' }
],
// 编辑器中的渲染函数
render: function(props) {
return '' + props.label + '
';
},
// 预览图标（可选）
icon: '📊'
});
```
### 5.2 组件接口要求
每个组件必须实现：
- `type` - 组件类型标识
- `defaultProps` - 默认属性对象
- `render(props)` - 返回 HTML 字符串
可选实现：
- `traits` - 属性定义数组，用于属性面板
- `icon` - 工具箱中显示的图标
- `onSelect()` - 选中时的回调
- `onDrop()` - 拖放完成后的回调
- `onDestroy()` - 销毁时的回调
---
## 六、显示端适配
### 6.1 手机端
- [x] 渲染在固定手机比例的 div 中
- [x] 使用 24 列网格
- [x] 组件位置和大小按比例显示
### 6.2 电脑端（预留）
- [ ] 未来扩展，暂不实现
- [ ] JSONB 格式已预留 computer 接口
---
## 七、文件结构
```
.
├── editor.html # 编辑器入口
├── css/
│ └── editor.css # 编辑器样式
├── js/
│ ├── editor/
│ │ └── editor.js # 编辑器主逻辑
│ └── lib/
│ └── webbuilder/ # 修改后的 webbuilder
│ ├── webbuilder.js
│ └── LICENSE
```
---
## 八、开发顺序
### 第一阶段：核心框架 ✅
1. ✅ 修改 webbuilder.js 核心类
2. ✅ 实现网格布局容器
3. ✅ 实现组件拖放定位
### 第二阶段：编辑器功能 ✅
4. ✅ 实现组件选中
5. ✅ 实现属性面板
6. ✅ 实现保存/加载
### 第三阶段：组件接口 ✅
7. ✅ 定义组件接口规范
8. ✅ 提供组件注册示例
### 第四阶段：完善功能
9. ✅ 实现 HTML 生成
10. ✅ 实现响应式适配
11. 实现显示页面
---
## 九、已确认事项
| 事项 | 决定 |
|------|------|
| 画布宽度 | 固定 375px |
| 画布高度 | 自适应（根据行数计算） |
| 网格粒度 | 24列 |
| 单元格比例 | 1:1（正方形） |
| 多端适配 | 仅支持手机端，电脑端预留接口 |
| 组件位置 | 使用 startCell + colSpan + rowSpan |
| 组件开发 | 框架只提供接口，使用者自定义实现 |
| 折线图 | 使用 Chart.js（使用者自行集成） |
---
*最后更新: 2026-03-29*