AI读取指南：UI 编辑器构建手册（狗子发布，2026/3/10）

03/10413 浏览综合

# AI 指南：UI 编辑器构建手册

读者：AI 开发助手

当用户要求做一个 UI 编辑器时，按本手册执行。

本手册与引擎无关，适用于任何支持 2D 渲染 + 鼠标输入的环境。

---

## §1 架构总览

UI 编辑器 = 数据模型 + 渲染器 + 交互系统 + 命令系统 + 序列化

```

用户操作 → 交互系统 → 命令系统 → 数据模型 → 渲染器 → 屏幕

↕

撤销重做栈

```

铁律：所有修改必须经过命令系统，不要直接改数据模型。

---

## §2 数据模型

### 2.1 节点结构

每个 UI 组件是一个节点，所有节点组成树形结构：

```

EditorNode = {

id string, -- 唯一标识（UUID 或自增 ID）

type string, -- 组件类型：panel, button, text, image, slider

name string, -- 用户可改的显示名：登录按钮

parent_id stringnil, -- 父节点 ID（根节点为 nil）

children string[], -- 子节点 ID 列表（有序）

-- 变换

x number, -- 相对于父节点的 X 偏移

y number, -- 相对于父节点的 Y 偏移

width number, -- 宽度

height number, -- 高度

rotation number, -- 旋转角度（度，可选，默认 0）

-- 外观

style table, -- 样式属性（见 §2.2）

-- 元数据

locked boolean, -- 锁定后不可选中移动

visible boolean, -- 是否可见

}

```

### 2.2 样式属性

```

style = {

-- 背景

bg_color string, -- 背景色 #RRGGBB 或 #RRGGBBAA

bg_image string, -- 背景图路径（可选）

border_color string, -- 边框色

border_width number, -- 边框宽度

corner_radius number, -- 圆角半径

-- 文本（仅 textbutton 类型）

text string, -- 文本内容

font_size number, -- 字号

font_color string, -- 字体颜色

text_align string, -- left center right

-- 透明度

opacity number, -- 0.0 ~ 1.0

}

```

### 2.3 编辑器状态

```

EditorState = {

nodes tablestring, EditorNode, -- 所有节点（ID → 节点）

root_id string, -- 根画布节点 ID

selection string[], -- 当前选中的节点 ID 列表

clipboard EditorNode[], -- 剪贴板

undo_stack Command[], -- 撤销栈

redo_stack Command[], -- 重做栈

-- 画布视图

canvas_offset_x number, -- 画布平移 X

canvas_offset_y number, -- 画布平移 Y

canvas_zoom number, -- 缩放比例（1.0 = 100%）

-- 交互状态

drag_mode stringnil, -- nil move resize select_box

drag_start_x number,

drag_start_y number,

resize_handle stringnil, -- tltrblbrtblr

}

```

---

## §3 模块拆分

文件组织（按职责拆分，不要写成单文件）：

```

ui_editor

├── data

│ ├── node.lua -- EditorNode 定义 + 工厂方法

│ ├── state.lua -- EditorState 管理（增删查改节点）

│ └── defaults.lua -- 各组件类型的默认属性

│

├── commands

│ ├── command.lua -- Command 基类（execute undo）

│ ├── move_command.lua -- 移动节点

│ ├── resize_command.lua -- 缩放节点

│ ├── add_command.lua -- 添加节点

│ ├── delete_command.lua -- 删除节点

│ ├── modify_command.lua -- 修改属性

│ └── batch_command.lua -- 批量命令（多个操作合为一次撤销）

│

├── interaction

│ ├── selection.lua -- 选中逻辑（单选多选框选）

│ ├── drag.lua -- 拖拽移动

│ ├── resize.lua -- 拖拽缩放

│ ├── snap.lua -- 对齐吸附（辅助线）

│ └── hotkeys.lua -- 快捷键绑定

│

├── render

│ ├── canvas.lua -- 画布渲染（网格背景 + 所有节点）

│ ├── node_renderer.lua -- 单个节点渲染（按 type 分发）

│ ├── selection_overlay.lua -- 选中高亮 + 缩放手柄

│ └── guides.lua -- 对齐辅助线渲染

│

├── panels

│ ├── component_panel.lua -- 左侧组件面板

│ ├── property_panel.lua -- 右侧属性面板

│ ├── layer_panel.lua -- 图层层级面板

│ └── toolbar.lua -- 顶部工具栏

│

├── serialization

│ ├── save.lua -- 导出为 JSON

│ ├── load.lua -- 从 JSON 导入

│ └── code_export.lua -- 导出为可运行代码（可选）

│

└── main.lua -- 入口：初始化 + 事件绑定 + 主循环

```

---

## §4 命令系统（核心）

必须实现，不可跳过。没有命令系统的编辑器无法撤销，等于不能用。

### 4.1 命令接口

```lua

Command = {

execute = function(self, state) end, -- 执行操作

undo = function(self, state) end, -- 撤销操作

name = 描述文字, -- 用于显示（可选）

}

```

### 4.2 命令管理器

```lua

function execute_command(state, cmd)

cmdexecute(state)

table.insert(state.undo_stack, cmd)

state.redo_stack = {} -- 新操作清空重做栈

end

function undo(state)

local cmd = table.remove(state.undo_stack)

if cmd then

cmdundo(state)

table.insert(state.redo_stack, cmd)

end

function redo(state)

local cmd = table.remove(state.redo_stack)

if cmd then

cmdexecute(state)

table.insert(state.undo_stack, cmd)

end

```

### 4.3 命令示例：移动

```lua

MoveCommand = {

node_ids = {}, -- 被移动的节点 ID 列表

dx = 0, dy = 0, -- 偏移量

old_positions = {}, -- 移动前的位置快照

}

function MoveCommandexecute(state)

self.old_positions = {}

for _, id in ipairs(self.node_ids) do

local node = state.nodes[id]

self.old_positions[id] = { x = node.x, y = node.y }

node.x = node.x + self.dx

node.y = node.y + self.dy

end

function MoveCommandundo(state)

for _, id in ipairs(self.node_ids) do

local pos = self.old_positions[id]

state.nodes[id].x = pos.x

state.nodes[id].y = pos.y

end

```

### 4.4 拖拽期间不要每帧创建命令

```

鼠标按下 → 记录起始位置

拖拽中 → 直接修改节点位置（临时，不创建命令）

鼠标松开 → 计算总偏移量 → 创建一个 MoveCommand → execute

```

这样一次拖拽 = 一次撤销，而不是几百个微小偏移命令。

---

## §5 交互系统

### 5.1 坐标转换

画布有平移和缩放，鼠标坐标需要转换：

```lua

-- 屏幕坐标 → 画布坐标

function screen_to_canvas(state, sx, sy)

local cx = (sx - state.canvas_offset_x) state.canvas_zoom

local cy = (sy - state.canvas_offset_y) state.canvas_zoom

return cx, cy

end

-- 画布坐标 → 屏幕坐标

function canvas_to_screen(state, cx, cy)

local sx = cx state.canvas_zoom + state.canvas_offset_x

local sy = cy state.canvas_zoom + state.canvas_offset_y

return sx, sy

end

```

### 5.2 命中检测

```lua

-- 判断画布坐标 (cx, cy) 是否在节点矩形内

function hit_test(node, cx, cy)

return cx = node.x

and cx = node.x + node.width

and cy = node.y

and cy = node.y + node.height

end

-- 从最上层往下找第一个命中的节点（后渲染的在上面）

function find_node_at(state, cx, cy)

-- 反向遍历（后添加的在上面）

local ordered = get_render_order(state)

for i = #ordered, 1, -1 do

local node = state.nodes[ordered[i]]

if not node.locked and node.visible and hit_test(node, cx, cy) then

return node.id

end

return nil

end

```

### 5.3 选中逻辑

```

点击空白处 → 清空选中

点击节点 → 单选该节点

Shift + 点击节点 → 切换该节点的选中状态（多选）

拖拽空白处 → 框选模式（选中矩形内所有节点）

```

### 5.4 缩放手柄

选中节点后显示 8 个手柄（四角 + 四边中点）：

```

tl ──── t ──── tr

│ │

l r

│ │

bl ──── b ──── br

```

每个手柄是一个小矩形（如 8x8 像素），命中时进入 resize 模式。

缩放约束：

- 按住 Shift → 保持宽高比

- 按住 Alt → 以中心点为锚点缩放

- 最小尺寸限制（如 10x10），防止缩放到负数

### 5.5 对齐吸附

拖拽时检测当前节点的边中线是否接近其他节点的边中线：

```

吸附检测的 5 条线（被拖拽的节点）：

左边水平中线右边上边垂直中线下边

对每条线，检测是否和其他节点的对应线距离阈值（如 5 像素）

如果是 → 吸附到该位置 + 画辅助线

```

---

## §6 渲染

### 6.1 渲染顺序

```

1. 画布背景（网格）

2. 所有节点（按层级顺序，父先子后，同级按 children 数组顺序）

3. 选中高亮 + 缩放手柄

4. 对齐辅助线

5. 框选矩形（如果正在框选）

6. UI 面板（组件面板属性面板工具栏）— 这些在画布之上

```

### 6.2 节点渲染分发

```lua

local renderers = {

panel = render_panel,

button = render_button,

text = render_text,

image = render_image,

slider = render_slider,

}

function render_node(node)

local fn = renderers[node.type]

if fn then fn(node) end

-- 递归渲染子节点

for _, child_id in ipairs(node.children) do

render_node(state.nodes[child_id])

end

```

### 6.3 画布网格

```lua

function render_grid(state, canvas_width, canvas_height)

local grid_size = 20 state.canvas_zoom

local offset_x = state.canvas_offset_x % grid_size

local offset_y = state.canvas_offset_y % grid_size

-- 用半透明线画网格

set_color(0.3, 0.3, 0.3, 0.3)

for x = offset_x, canvas_width, grid_size do

draw_line(x, 0, x, canvas_height)

end

for y = offset_y, canvas_height, grid_size do

draw_line(0, y, canvas_width, y)

end

```

---

## §7 属性面板

### 7.1 属性分组

```

基础

├─ 名称 [文本输入]

├─ 类型 [只读标签]

├─ 可见 [复选框]

└─ 锁定 [复选框]

变换

├─ X Y [数值输入]

├─ 宽度高度 [数值输入]

└─ 旋转 [数值输入 + 滑块]

外观

├─ 背景色 [颜色选择器]

├─ 边框色 [颜色选择器]

├─ 边框宽度 [数值输入]

├─ 圆角 [数值输入]

└─ 透明度 [滑块]

文本（仅 textbutton）

├─ 内容 [文本输入]

├─ 字号 [数值输入]

├─ 字体颜色 [颜色选择器]

└─ 对齐 [三选一按钮：左中右]

```

### 7.2 属性修改 → 命令

属性面板的每次修改必须走命令系统：

```lua

-- 用户在属性面板改了字号

function on_property_change(node_id, key, old_value, new_value)

local cmd = ModifyCommandnew(node_id, key, old_value, new_value)

execute_command(state, cmd)

end

```

数值输入框优化：用户拖拽数值滑块时不要每帧创建命令，松开时创建一个。

---

## §8 序列化

### 8.1 保存格式（JSON）

```json

{

version 1,

canvas { width 1920, height 1080 },

nodes [

{

id node_1,

type panel,

name 根面板,

parent_id null,

children [node_2, node_3],

x 0, y 0, width 400, height 300,

style { bg_color #2A2A2A, corner_radius 8 }

{

id node_2,

type button,

name 登录按钮,

parent_id node_1,

children [],

x 100, y 200, width 200, height 50,

style { text 登录, bg_color #4A90D9, font_size 18 }

}

]

}

```

### 8.2 代码导出（可选）

把节点树转换成可运行的 UI 代码。输出格式取决于目标框架。

核心逻辑：递归遍历节点树，为每个节点生成对应的构造代码。

---

## §9 实现顺序（必须遵守）

不要跳步，每步完成后 build + 测试再进入下一步。

阶段内容验收标准

---------------------

1 数据模型 + 状态管理能创建删除查找节点

2 画布渲染（网格 + 矩形节点）屏幕上能看到节点

3 坐标转换 + 命中检测点击节点能识别

4 选中逻辑 + 高亮渲染点击节点出现蓝色边框

5 命令系统 + 撤销重做 Ctrl+ZY 能正常工作

6 组件面板（点击添加）点左栏按钮→ 画布出现新节点

7 拖拽移动拖拽节点移动，松开后可撤销

8 属性面板（查看 + 修改）选中节点 → 右栏显示属性 → 修改生效

9 拖拽缩放 + 手柄拖角手柄缩放节点

10 多选 + 框选 Shift 多选 + 拖空白处框选

11 删除 + 复制粘贴 DeleteCtrl+CCtrl+V

12 保存加载 JSON 导出文件 → 重新导入 → 布局一致

13 对齐吸附 + 辅助线拖拽接近时出现辅助线并吸附

14 层级面板显示节点树，可拖拽调整顺序

15 视觉打磨深色主题 + 图标 + 动画过渡

---

## §10 注意事项

### 10.1 性能

- 节点数 100 时不需要优化，直接全量重绘

- 超过 100 个节点 → 脏标记机制（只重绘变化的部分）

- 属性面板不要每帧重建，只在选中变化时更新

### 10.2 ID 生成

- 用自增整数即可（`node_1`, `node_2`, ...）

- 保持全局计数器，删除节点不回收 ID

- 确保 ID 在保存加载后不重复

### 10.3 父子关系

- 移动父节点时，子节点跟随移动（因为子节点坐标是相对父节点的）

- 删除父节点时，递归删除所有子节点

- 拖拽改变父子关系时（从层级面板），要更新坐标（从旧父节点的相对坐标转换到新父节点的相对坐标）

### 10.4 多选操作

- 移动多个选中节点 → 一个 BatchCommand 包含多个 MoveCommand

- 删除多个选中节点 → 一个 BatchCommand 包含多个 DeleteCommand

- 确保一次撤销能还原整个批量操作

### 10.5 画布导航

- 鼠标中键拖拽 → 画布平移

- 滚轮 → 画布缩放（以鼠标位置为中心点）

- 缩放范围限制：25% ~ 400%

- 提供适配画布按钮（自动缩放到全部节点可见）

---

本手册供 AI 读取，指导 UI 编辑器的完整实现。

猜你想搜

taptap 制造数据模型定义

TapTap 制造应用

9.8

前往论坛