UI 重构 P0+P1：新增布局/控件基础层与离屏回归网（对产品像素零影响）
新增 Components/Shared 下的 UI 基础层： - UiLayout：矩形原语 / 对齐 / 设备像素内侧对齐 / Stack / Flow / 布局缓存（deque 保证引用稳定、 定向失效、按最久未命中淘汰）。 - UiWidget：控件树基类。两段式布局（Measure 自下而上带缓存、Arrange 自上而下）、 脏区下探绘制（dirty 为空=全画；与子树矩形无交集=整棵跳过；有效裁剪=祖先裁剪切∩自身∩脏区）、 只沿命中链派发的冒泡模型（绝不分发给同层兄弟）、capture/modal/hover/focus 仲裁、 光标认领链、统一动画 tick、内容指纹入口。 新增 Tools/uicheck 离屏回归网（62 项断言，全程不创建窗口、不注入输入）： - 布局数学：对齐/STRETCH/超尺寸夹取、Stack 固定与自动均分且绝不产生负尺寸、Flow 换行与 overflow。 - 缓存：引用稳定、定向失效、容量淘汰。 - 绘制：全画 / 子树跳过 / 裁剪收窄 / 不可见跳过 / 失效冒泡。 - 派发：重叠子节点只投最上层、hit-transparent 穿透、消费不上抛、capture 越过边界仍投递、 仅持有者可释放、modal 屏蔽其余子树、祖先兜底、光标由最上层认领、键盘沿焦点链。 - 动画：时间戳统一下发、活跃状态汇总。 过程中修正自身两处缺陷：补齐 AdvanceAnimationSelf/AnimationActiveSelf 声明； 把"遍历同层兄弟"改为"只沿命中链派发 + 祖先兜底"（否则一次点击可能被视觉上位于下方的控件也处理）。 验证：make release TARGET_FILE_NAME=TargetCheck 零警告（873,984 B，低于 900KB 阈值）； Tools/uicheck 62 passed / 0 failed。 本提交不改动任何现有组件，Toolbar/TabBar/SignalPanel/PlotView 仍走旧路径，产品像素零变化。 文档：Documents/UI_Refactor_Plan.md（蓝图）、Documents/UI_Refactor_Progress.md（台账）。
This commit is contained in:
DeepSeek V4.1 Flash committed
1 parent
4e51b41a42
commit
3529c7b44f
6 files changed
+1906
No files matched your search
@@ -0,0 +1,304 @@
|
||||
# UI 重构计划（UI_Refactor 分支）
|
||||
|
||||
> 目标读者：本项目的后续 Agent（可能是另一台设备 / 另一个模型）。
|
||||
> 本文是**唯一施工蓝图**；实时进度见 `Documents/UI_Refactor_Progress.md`，最终结论见 `Documents/UI_Refactor_Report.md`。
|
||||
> 硬约束的权威来源仍是 `Documents/agent_mem.md`（§11.2）；本文与之冲突时**以 agent_mem.md 为准**。
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么要重构（量化基线）
|
||||
|
||||
| 指标 | 现状 | 出处 |
|
||||
| --- | --- | --- |
|
||||
| `PlotViewPaint.cpp` | **9 080 行**（注释 1 295 / 空行 517 / 仅大括号 2 026 / **有效代码 5 242**） | `Get-Content \| Measure-Object` |
|
||||
| `PlotView.hpp` | 3 649 行、**310 个方法**、**203 个成员变量**、31 个嵌套类型 | 同上 |
|
||||
| `EdgePanelLayoutFor` | **651 行**、**19 个调用点**，每帧被命中/层序/光标/绘制各算一遍 | `Select-String` |
|
||||
| `Application.cpp` 的 `InvalidateRect` | **56 处** + 手写 `m_chromeDirty` / `m_panelDirty` / `panelOnly` / `fullFrame` 组合 | 同上 |
|
||||
| 动画 | **5 套**手写动画散在 3 个组件，共用一个 10ms 定时器 | 同上 |
|
||||
| 自动化 UI 探针 | **0**（`.preflight` 已被删除且被 gitignore） | 仓库现状 |
|
||||
|
||||
`PlotViewPaint.cpp` 里混住四类内容：真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / **布局与命中几何 ≈1.3k**。
|
||||
|
||||
**五条根因**
|
||||
|
||||
1. 上次拆 13 695 行大文件时按**函数名**（"带 `Paint` 前缀"）而非**关注点**分片 ⇒ 缓存、缓存键、面板布局、命中几何全被倒进 paint 分片。
|
||||
2. 没有控件抽象 ⇒ 每个叠加层自带"几何 + 命中 + 绘制 + 缓存键"四份重复；5 个实验性面板各 800~1 200 行，靠 10 多个平行数组（`rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...`）下标对齐"假装"成树。
|
||||
3. GDI / GDI+ 双栈妥协被**每个绘制点重复支付**（GDI 文本不认 GDI+ 裁剪、`UiFillRect` 的 GDI 快路径绕过裁剪、GDI 文本忽略 alpha…）。
|
||||
4. "必须混进缓存键，否则贴旧像素"这条不变量**没有归属**（4 套手写 key + 一堆 `Collect*` ≈1.1k 行；历史 ≥4 次真实 BUG 是"忘了混一个字段"）。
|
||||
5. 1 295 行硬核"为什么"注释让行数虚高 —— **保留，不删**（多 Agent 协作防回归的核心资产）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计目标与非目标
|
||||
|
||||
### 1.1 目标（必须达成）
|
||||
|
||||
1. **几何只算一次**：布局是"按需失效的 pass"，命中/绘制/光标共用同一份结果。
|
||||
2. **失效从布尔变矩形**：`dirty ∩ bounds` 为空 ⇒ 整棵子树跳过（这是唯一真正省钱的层次）。
|
||||
3. **裁剪契约统一**：`Paint` 进入时同时收紧 GDI 裁剪与 GDI+ 裁剪，根治"文字画到图例/工具栏上"这类已出现 3 次的 BUG。
|
||||
4. **缓存键有归属**：由"持有该内容的节点"产生，父层只聚合。
|
||||
5. **事件派发显式化**：`{consumed, redraw, dirtyRect}` 代替 `bool 要不要重绘`；capture / 模态 / hover / 焦点 / 光标仲裁由基类提供。
|
||||
6. **动画统一 tick**：一个动画列表 + 现有 `kScrollTimerId` 推进。
|
||||
7. **零行为变更的先行阶段**：先拆文件、补回归网，再动语义。
|
||||
|
||||
### 1.2 非目标（明确不做，写进禁区）
|
||||
|
||||
| 禁区 | 原因 |
|
||||
| --- | --- |
|
||||
| ❌ 波形数据→像素管线控件化（网格/曲线/采样点不做成节点） | 布局与虚调用会进每帧热路径；采样/顶点量与控件无关 |
|
||||
| ❌ 每个控件自持位图 | 内存按面积线性增长：逐网格图层已是屏幕面积 2 倍（5 网格 ≈16MB，**128 网格 ≈250MB**） |
|
||||
| ❌ "父脏 ⇒ 子树全脏" | 会把"只重绘一个网格/一个面板"打回整块重绘（历史最易发生的退化） |
|
||||
| ❌ 多线程光栅 | GDI+ 内部串行，实测 **1.03x**；且后台改写 `m_area`/`ViewMin` 会覆盖用户平移（第一代已因此回退） |
|
||||
| ❌ 逐控件细粒度像素缓存 | 画一个按钮 20~80µs vs 贴图 5~10µs ⇒ 净亏损，还要付"忘混键"的风险 |
|
||||
| ❌ 引入属性对象体系（学 Blink） | 那是为 Blink 规模准备的；本项目用"节点产生 key"即可 |
|
||||
|
||||
### 1.3 借鉴来源与取舍
|
||||
|
||||
| 借鉴 | 采纳 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Chromium `views::View` 的**失效驱动布局 pass** | ✅ 全采纳 | 对应 §3 的 `UiWidget::Measure/Arrange` + `UiLayoutCache` |
|
||||
| `views::View::PaintChildren` 的**脏矩形下探** | ✅ 全采纳 | 对应 §4 的 `PaintContext.dirty` |
|
||||
| `SetPaintToLayer()` 只提升**少数**子树 | ✅ 保持现状量级（4 层） | 不再新增层 |
|
||||
| `cc` 的**记录-光栅分离 / tiling / checkerboarding / 每帧预算** | ✅ 已具备，不改 | `PolylineCacheEntry`、宽基底+补条、贴过期但位置正确、`RenderPendingLaneRebuilds(1)` |
|
||||
| `cc` 的**多线程光栅 / GPU 合成** | ❌ 不采纳 | GDI+ 无 GPU 路径；并行实测 1.03x |
|
||||
| Dear ImGui 的**每帧全量重画** | ❌ 不采纳 | 本项目整幅重绘 ≈80ms，必须走失效 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标架构
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
H[UiHost<br/>持有 app-sized 32bpp top-down DIB<br/>z 序 · 脏区并集 · 一次 BitBlt 回送 · 动画 tick]
|
||||
H --> R[UiRoot : UiWidget]
|
||||
R --> D{脏区树<br/>dirty ∩ bounds 空 ⇒ 整棵子树 return}
|
||||
D --> A[普通控件：直接画进共享缓冲<br/>按钮 / 文本 / 列表行 / 时间轴 / 图例]
|
||||
D --> B[高成本叶子：自持位图，完成即 BitBlt 贴回<br/>波形网格 / 装饰层 / 光晕 / 浮动面板]
|
||||
A --> S[SurfaceView{ dc, rect, stride, bits, version }]
|
||||
B --> S
|
||||
```
|
||||
|
||||
**分层原则**
|
||||
|
||||
- **共享一张缓冲**：省内存、免分配抖动、合成顺序天然确定。
|
||||
- **只有高成本叶子自持缓冲**：这是"把重画换成贴图"的唯一手段。
|
||||
- **脏区向下取交集**（不是并集）。
|
||||
- **布局由下往上、每帧最多一轮 Measure**；尺寸由内容反推（`EdgePanelWidth` 就是这种）。
|
||||
|
||||
### 2.1 新增文件
|
||||
|
||||
| 文件 | 职责 | 依赖 |
|
||||
| --- | --- | --- |
|
||||
| `Components/Shared/Inc/UiLayout.hpp` / `Src/UiLayout.cpp` | 纯几何：`UiInsets`、栈/流/锚点/对齐、`UiLayoutCache` | 仅 `Theme.hpp`（`gd::RectF`） |
|
||||
| `Components/Shared/Inc/UiWidget.hpp` / `Src/UiWidget.cpp` | 控件基类：树、Measure/Arrange、双栈裁剪 Paint、事件派发、失效、capture/模态/hover/焦点/光标、动画 tick | `UiLayout.hpp`、`PaintUtil.hpp` |
|
||||
| `Components/Shared/Inc/UiHost.hpp` / `Src/UiHost.cpp` | 宿主：共享 DIB + `SurfaceView` + 脏区并集 + 回送 + 消息翻译 + 动画定时器 | `UiWidget.hpp` |
|
||||
| `Tools/uicheck/`（入库） | 离屏回归网（`SW_HIDE` + 注入消息 + 从 `m_backDc` 取帧） | `Build/Release/*.o` |
|
||||
|
||||
> ⚠️ `Components/Shared` 已在 `Makefile` 的 `CXX_INCLUDES_PATHS` / `CXX_SOURCES_PATHS` 中 ⇒ 新增 `.cpp` **无需改 Makefile**（按 basename 自动收集）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局层设计（`UiLayout`）
|
||||
|
||||
### 3.1 为什么不是简单的"宽高字段"
|
||||
|
||||
基类若只有 `width/height`，会在三处立刻失效：
|
||||
|
||||
1. 所有坐标是**逻辑像素 × scale**（本机 DPR 1.25），控件必须知道缩放；
|
||||
2. 面板宽度是**由内容反推**（`EdgePanelWidth` = 列宽 max + 行 ✕ + 滚动条预留）；
|
||||
3. 离屏位图要求**设备像素整数对齐**（`floor`/`ceil` 方向错了就留 1px 接缝 —— 样式补丁曾踩过）。
|
||||
|
||||
⇒ 采用 **`Measure(约束) → 期望尺寸` / `Arrange(最终矩形) → 实际矩形`** 两段式。
|
||||
|
||||
### 3.2 需要的布局种类（按实际用量排序）
|
||||
|
||||
| 布局 | 用途 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| **Abs（绝对）** | 绘图区叠加物主力：光标线、取值胶囊、吸附环、越界三角、固定点、面板初始位置、滚动条 | 保留"自由布局"，但它是**主力**而非备选 |
|
||||
| **Anchor（四边贴合）** | 工具栏整体靠右、时间轴贴底、滚动条贴右、面板夹在 `m_plotRect` 内 | 讨论中缺失，必须补 |
|
||||
| **Stack（竖向流）** | 信号列表行、分组行、面板条目（名称行 + 参数行 + 滑块行） | 需支持"行高由内容决定 + 吸顶(sticky) + 滚动视口" |
|
||||
| **Flow（横向流 + 溢出）** | 图例条目 + 空间不足的 `+N`、工具栏按钮组 | 讨论中缺失，必须补 |
|
||||
| **Measure-driven** | 面板宽度按实测文本撑开、列宽 `max(缺省, 内容, 列标题)` | 必须有，否则又回到"绘制侧省略号" |
|
||||
| Grid | **用不上**（绘图区不是表格） | 不实现 |
|
||||
| Card | 只是"面板皮肤" | 作为 `UiPanelSkin` 绘制样式，不是布局 |
|
||||
|
||||
### 3.3 `UiLayoutCache`（本次最关键的性能点）
|
||||
|
||||
`EdgePanelLayoutFor` 的 19 个调用点全部来自"同一份几何被反复问"。做法：
|
||||
|
||||
```cpp
|
||||
class UiLayoutCache
|
||||
{
|
||||
public:
|
||||
// key 由调用方提供（例如 laneIndex + kind + 面板宽 + 缩放 + 条目数）
|
||||
const LayoutEntry* Find(std::uint64_t key) const;
|
||||
const LayoutEntry& Store(std::uint64_t key, LayoutEntry&& entry);
|
||||
void Invalidate(std::uint64_t key); // 定向失效
|
||||
void Clear();
|
||||
};
|
||||
```
|
||||
|
||||
**硬约束**：`Invalidate` 必须由"改变几何的那条路径"**显式**调用（与 `m_edgeScans` 的定向失效同一纪律），**禁止**为了让缓存命中率好看而整体 `Clear()`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 控件基类设计（`UiWidget`）
|
||||
|
||||
### 4.1 接口骨架
|
||||
|
||||
```cpp
|
||||
struct UiEventResult
|
||||
{
|
||||
bool consumed = false; // 事件已被消费（不再下传/上抛）
|
||||
bool redraw = false; // 需要重绘
|
||||
gd::RectF dirty; // 需要重绘的矩形（客户区坐标；空 = 未知 ⇒ 取自身 bounds）
|
||||
};
|
||||
|
||||
class UiWidget
|
||||
{
|
||||
public:
|
||||
virtual ~UiWidget();
|
||||
|
||||
// ---- 树 ----
|
||||
void AddChild(std::unique_ptr<UiWidget> child);
|
||||
void RemoveChild(UiWidget* child);
|
||||
const std::vector<std::unique_ptr<UiWidget>>& Children() const;
|
||||
|
||||
// ---- 布局（两段式，各自带失效）----
|
||||
void InvalidateMeasure(); // 向上冒泡到根
|
||||
void InvalidateArrange();
|
||||
gd::SizeF Measure(const UiMeasureContext& ctx); // 自下而上，命中缓存则直接返回
|
||||
void Arrange(const gd::RectF& bounds); // 自上而下；bounds 一定 > 0
|
||||
|
||||
// ---- 绘制（双栈裁剪 + 脏区下探）----
|
||||
void Paint(UiPaintContext& ctx); // 内部：与 dirty 求交 → OnPaint → 递归子节点
|
||||
virtual void Invalidate(const gd::RectF& rect); // 局部失效（向上冒泡并入）
|
||||
|
||||
// ---- 事件 ----
|
||||
UiEventResult Dispatch(UiEvent& event); // 命中 → 子节点（反 z 序）→ OnEvent
|
||||
|
||||
// ---- 命中 / 光标 ----
|
||||
bool Contains(int x, int y) const;
|
||||
virtual HCURSOR QueryCursor(int x, int y) { return nullptr; }
|
||||
|
||||
// ---- 交互仲裁（由 Host 调用）----
|
||||
UiWidget* Capture(); void SetCapture(); void ReleaseCapture();
|
||||
void SetModal(bool modal); // 模态子树：Host 只向它派发
|
||||
void SetHitTransparent(bool value); // 装饰元素：不参与命中
|
||||
|
||||
// ---- 动画 ----
|
||||
virtual bool AdvanceAnimation(std::int64_t nowMs) { return false; }
|
||||
|
||||
protected:
|
||||
virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0;
|
||||
virtual void OnArrange() {}
|
||||
virtual void OnPaint(UiPaintContext& ctx) = 0;
|
||||
virtual UiEventResult OnEvent(UiEvent& event) { return {}; }
|
||||
virtual std::uint64_t ContentKey() const; // 缓存键的来源（父层只聚合）
|
||||
};
|
||||
```
|
||||
|
||||
### 4.2 `Paint` 的硬契约（必须由基类保证，不是"每个控件记得"）
|
||||
|
||||
1. **双栈裁剪**：进入时 `SaveDC + IntersectClipRect`（GDI）+ `Graphics::SetClip(Intersect)`（GDI+），退出时还原。这一条一次性消灭"滚动时文字串到标题栏""全选高亮溢出输入框""选区画到工具栏上"。
|
||||
2. **脏区下探**：`ctx.dirty = ctx.dirty ∩ bounds`；若为空 ⇒ **整棵子树直接 return**（不调 `OnPaint`、不遍历子节点）。
|
||||
3. **绘制顺序 = 子节点顺序 = z 序**；命中/事件 = **反 z 序**（与现在 `m_panelOrder` + `TopPanelAtPoint` 反向遍历等价，但不再靠人工维护）。
|
||||
4. **禁止**在 `OnPaint` 内改 `bounds`/子节点集合（会与本帧的 dirty 不一致）。
|
||||
|
||||
### 4.3 事件派发的硬契约
|
||||
|
||||
- **`consumed`** 决定是否上抛；**`dirty`** 参与本帧脏区并集。
|
||||
- **capture**：抓取期间所有鼠标事件**直接投给抓取者**（跳过命中），与 Windows `SetCapture` 语义一致。本项目硬约束：中键平移与左键拖拽**共用同一个 capture**，松左键**不能**无条件 `ReleaseCapture()`。
|
||||
- **模态**：菜单打开时 Host 只向模态子树派发，且"取消底层拖拽"时必须**排除菜单自己的 `EDIT_FIELD`**。
|
||||
- **hover**：Host 维护 hover 链，跨节点 `leave/enter`；悬停是**跨组件**的（面板行 → 网格固定点高亮；列表行 → 曲线光晕）⇒ 通过 Host 级"悬停信号总线"广播，不靠父子关系。
|
||||
- **双击消歧**：窗口带 `CS_DBLCLKS`；没有双击语义的位置必须在 `DoubleClickIsPlainPress()` 返回 true，由 Host 改走普通按下（否则"连点丢一半"）。
|
||||
|
||||
### 4.4 失效契约
|
||||
|
||||
- 节点持 `m_dirty`（自身坐标系）+ `m_dirtyChildren`；
|
||||
- `Invalidate(rect)` 并入自身并**向上冒泡**（父层只并集矩形，**绝不**把子树的 dirty 清零）；
|
||||
- Root 暴露 `TakeDirty()` 给 Host，Host 再与窗口更新区域取并集。
|
||||
|
||||
---
|
||||
|
||||
## 5. 宿主层设计（`UiHost`）
|
||||
|
||||
1. **单一 app-sized 32bpp top-down DIB**（替换现在的 `CreateCompatibleBitmap`）：
|
||||
```cpp
|
||||
struct SurfaceView
|
||||
{
|
||||
HDC dc; // 共享 HDC（GDI/GDI+ 都画这个）
|
||||
gd::RectF rect; // 本节点在 Holder 坐标系中的矩形（设备像素，整数对齐）
|
||||
int stride; // 行字节数（**不可**假设 = width*4）
|
||||
std::uint32_t* bits; // rect 左上角那一像素（不是位图首地址）
|
||||
std::uint64_t version; // 位图代次；失配 ⇒ 句柄作废
|
||||
};
|
||||
```
|
||||
⚠️ **绝不能缓存裸指针**：`EnsureBackBuffer` 在 `WM_SIZE` / `WM_DPICHANGED` 会重建位图。
|
||||
⚠️ `bits` 只在 **CPU 侧直写**（memcpy/alpha）时用；GDI/GDI+ 绘制只需 `dc + rect`。
|
||||
2. **脏区并集**：把现在 56 处 `InvalidateRect` 收敛为 `Host::Invalidate(rect)`，一次回送。
|
||||
⚠️ 回送仍必须**有无条件 `else`**（历史：某分支缺兜底 ⇒ 窗口一个像素都不回送，用户看到三个不同症状）。
|
||||
3. **动画 tick**：`AdvanceAnimation` 遍历树，任一为 true 就保持 `kScrollTimerId`（10ms）。
|
||||
4. **消息翻译**：`WM_*` → `UiEvent`，并把 `WM_SETCURSOR` 交给 `QueryCursor` 链（从 z 顶向下、首个非 null 生效）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 落地阶段（每阶段一个可独立回滚的提交）
|
||||
|
||||
| 阶段 | 内容 | 交付判据 |
|
||||
| --- | --- | --- |
|
||||
| **P0** | 离屏回归网 `Tools/uicheck`（入库）+ 现有 20+ 条硬约束的断言骨架 | 能一键跑；对现版本全绿 |
|
||||
| **P1** | `UiLayout` + `UiWidget` 基础层（本次） | 编译零警告；`uicheck` 覆盖布局数学 + 派发/裁剪/脏区/动画 |
|
||||
| **P2** | 零行为变更分片：`PlotViewPaint.cpp` 拆成 `Paint`（只画）/ `Raster`（缓存与预算）/ `CacheKey`（指纹）/ `Geometry`（面板与命中）；`EdgePanelLayoutFor`、`ProbeFreeMarker` 迁回交互侧 | **逐像素 0 差异**（用 P0 的场景哈希断言） |
|
||||
| **P3** | 迁移 chrome：Toolbar → TabBar → PopupMenu → ColorPicker → SignalPanel 行（**一次一个组件、每完成一个跑全量探针**） | 每个组件迁移后 `uicheck` 全绿 + 手工契约断言 |
|
||||
| **P4** | 迁移 5 个浮动面板（`EdgePanelLayoutFor` 651 行 → 真控件；消掉平行数组） | 同上；`EdgePanelLayoutFor` 行数下降 >60% |
|
||||
| **P5** | 波形管线包成叶子 surface（**只包不改**）+ 共享 DIB 落地 | `uicheck` 全绿；`Target.exe` ≤ 900KB |
|
||||
|
||||
**P2 之前禁止改任何行为**。P2 是唯一的"免费"阶段，别顺手改语义。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证策略（不占用用户鼠标/键盘/屏幕）
|
||||
|
||||
1. **离屏 harness**：`SW_HIDE` 窗口 + 直接 `app.HandleMessage(...)` 注入 + 从 `m_backDc` 用 `GetDIBits` 取帧。
|
||||
2. **进程/线程优先级 `BELOW_NORMAL`**；从不用 `SetCursorPos` / `SendInput` / 截屏。
|
||||
3. **A/B 反证**：每条新断言都要能被"还原旧实现"证伪，否则不算通过。
|
||||
4. **像素判据要选对区域**：验证"某交互不应改变外观"时，只对**不受影响**的区域取哈希。
|
||||
5. **已知陷阱**（全部来自历史 BUG）：
|
||||
- 探针消息泵必须丢弃 `WM_MOUSELEAVE`（离屏窗口会立刻兑现它）；
|
||||
- 注入按下后立即 `ReleaseCapture()`（避免抢真实鼠标）；
|
||||
- `CycleCursorMode()` 是**循环**，多组用例里重复调用会把光标关掉；
|
||||
- `PlotView` 的嵌套类型（`LaneVisual`/`LegendHit`/`EdgePanelLayout`）使用时要写 `PlotView::` 前缀。
|
||||
|
||||
---
|
||||
|
||||
## 8. 协作纪律（多 Agent）
|
||||
|
||||
1. **文件所有权**：同一时刻**一个 Agent 只改一个文件的同一区域**；跨阶段并行时按下表分工，禁止交叉。
|
||||
2. **每阶段一个提交**，提交信息写清"改了什么 / 为什么 / 怎么验证"。
|
||||
3. **先写断言再改代码**。
|
||||
4. `main` / `dev` 只接受全绿；`UI_Refactor` 内允许临时红，但**不许跨轮次累积红**。
|
||||
5. 任何"规则变更"必须同步进 `Documents/agent_mem.md`（§11.2 追加编号），否则另一端看不到。
|
||||
6. 体积红线 **900KB**（到达即提醒用户，不是禁止超过）。
|
||||
|
||||
### 8.1 并行分工建议（若启用多个 Agent）
|
||||
|
||||
| Agent | 独占文件 | 禁止触碰 |
|
||||
| --- | --- | --- |
|
||||
| A（基础层） | `UiLayout.*`、`UiWidget.*`、`UiHost.*`、`Tools/uicheck/*` | 任何现有组件 |
|
||||
| B（分片） | `PlotViewPaint.cpp` → 新分片文件、`PlotViewInternal.hpp` 的 include 段 | `UiWidget.*`、面板逻辑 |
|
||||
| C（面板迁移） | `PlotViewFeatures.cpp` 的面板段、新建 `PlotViewPanels.cpp` | `PlotViewPaint.cpp`、`UiLayout.*` |
|
||||
|
||||
> 冲突高发点：`Makefile`（新增目录时才需要改）、`agent_mem.md`（追加编号必须串行）。
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险与回滚
|
||||
|
||||
| 风险 | 触发条件 | 回滚 |
|
||||
| --- | --- | --- |
|
||||
| 迁移后"连点丢一半" | `DoubleClickIsPlainPress` 语义漏实现 | 单组件提交可独立 revert |
|
||||
| 迁移后"拖动卡住" | capture 共用被拆成两套 | 同上 |
|
||||
| 面板失效不全（贴旧像素） | `ContentKey()` 漏字段 | P4 里每个面板配一条"改 X 后像素必须变"的断言 |
|
||||
| 体积超 900KB | 新框架代码量 | 每阶段结束量一次；超阈值先报告用户 |
|
||||
| 布局级联死循环 | Measure 里改子节点 | 单元测试固定"Measure 一轮即收敛" |
|
||||
@@ -0,0 +1,86 @@
|
||||
# UI 重构进度（UI_Refactor 分支）
|
||||
|
||||
> 本文件是**跨会话/跨 Agent 的交接台账**。每次提交前更新；每一行都要能对应到一个可复跑的验证结果。
|
||||
> 计划见 `Documents/UI_Refactor_Plan.md`；硬约束见 `Documents/agent_mem.md` §11.2。
|
||||
|
||||
## 分支状态
|
||||
|
||||
| 分支 | 基线 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `main` | `df715a0` | 可发布，**不受本次重构影响** |
|
||||
| `dev` | `4e51b41`（删除过时报告 `refactor_report_2026-10-16.md`） | 日常开发基线 |
|
||||
| `UI_Refactor` | 从 `dev` 切出 | 本次 UI 重构（全部提交只留在本地） |
|
||||
|
||||
## 阶段看板
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
| --- | --- | --- |
|
||||
| **P0** | 离屏回归网 `Tools/uicheck`（入库） | ✅ 完成（62 项断言全绿） |
|
||||
| **P1** | `UiLayout` + `UiWidget` 基础层 | ✅ 完成（编译零警告，`uicheck` 覆盖） |
|
||||
| **P2** | `PlotViewPaint.cpp` 零行为分片 | ⏳ 待做 |
|
||||
| **P3** | 迁移 chrome（Toolbar / TabBar / 菜单 / 拾色器 / 列表行） | ⏳ 待做 |
|
||||
| **P4** | 迁移 5 个浮动面板 | ⏳ 待做 |
|
||||
| **P5** | 波形管线包成叶子 surface + 共享 DIB | ⏳ 待做 |
|
||||
|
||||
---
|
||||
|
||||
## 提交记录
|
||||
|
||||
### 1. `P0 + P1`：UI 基础层与离屏回归网
|
||||
|
||||
**新增文件**
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
| --- | --- | --- |
|
||||
| `Components/Shared/Inc/UiLayout.hpp` | ~250 | 布局原语 + `UiLayoutCache` |
|
||||
| `Components/Shared/Src/UiLayout.cpp` | ~300 | 矩形原语 / 对齐 / Stack / Flow / 缓存 |
|
||||
| `Components/Shared/Inc/UiWidget.hpp` | ~330 | 控件基类接口与设计说明 |
|
||||
| `Components/Shared/Src/UiWidget.cpp` | ~560 | 树 / Measure·Arrange / Paint（脏区+裁剪）/ 派发 / 仲裁 / 动画 |
|
||||
| `Tools/uicheck/main.cpp` | ~570 | 离屏回归网（62 项断言） |
|
||||
| `Tools/uicheck/build.ps1` | ~70 | 链接 `Build/<Config>/*.o`（排除 `Main.o`） |
|
||||
|
||||
**已实现并验证的行为**
|
||||
|
||||
- 布局：`UiAlignInRect`（含 `STRETCH`、超尺寸夹取、偏移后置）、`UiRectSnapInward`（设备像素内侧对齐）、
|
||||
`UiStackRects`（固定 / `kUiSizeAuto` 均分 / **绝不产生负尺寸**）、`UiFlowRects`（换行 + `overflow` 下标）。
|
||||
- 缓存：`UiLayoutCache` 用 `std::deque` 保证**引用稳定**；容量淘汰按"最久未命中"；`Invalidate` 为**定向**失效。
|
||||
- 布局 pass：`Measure` 命中缓存不重复调用 `OnMeasure`；`InvalidateMeasure` **只**沿祖先链失效（兄弟不重算）。
|
||||
- 绘制：`dirty` 为空 = 全画；与子树矩形无交集 ⇒ **整棵子树跳过**；有效裁剪 = 祖先裁剪切 ∩ 自身矩形 ∩ 脏区；
|
||||
不可见节点跳过。
|
||||
- 派发：**只沿命中链**（最深的命中节点 → 祖先冒泡），**绝不分发给同层兄弟**；`capture` 期间事件直投捕获者；
|
||||
`modal` 只向模态子树派发；`hit-transparent` 让事件穿透；`QUERY_CURSOR` 由最上层认领者返回；
|
||||
键盘/字符沿**焦点链**派发（无焦点交给根，保证宿主级快捷键可用）。
|
||||
- 动画：`AdvanceAnimation` 逐节点下发同一时间戳并汇总"是否仍有动画"。
|
||||
- 悬停：进入 / 离开各只触发一次，跨子节点迁移时正确配对。
|
||||
|
||||
**过程中修掉的两个自身缺陷**
|
||||
|
||||
1. `UiWidget` 缺 `AdvanceAnimationSelf` / `AnimationActiveSelf` 两个 protected 虚函数（`.cpp` 已引用、头文件漏声明）。
|
||||
2. 最初的派发实现是"遍历同层兄弟、未消费就继续" ⇒ **一个点击可能同时被视觉上位于下方的控件处理**；
|
||||
已改为"只沿命中链派发 + 祖先兜底"。回归网里对应的断言从"绝对次数"改为**增量断言**
|
||||
（绝对次数会被前面用例计数污染，本轮踩过一次）。
|
||||
|
||||
**验证**
|
||||
|
||||
```
|
||||
make release TARGET_FILE_NAME=TargetCheck # 零警告
|
||||
powershell -File Tools/uicheck/build.ps1 # 链接 Build/Release/*.o（排除 Main.o）
|
||||
Tools/uicheck/uicheck.exe # 62 passed, 0 failed
|
||||
```
|
||||
|
||||
**未做（有意）**
|
||||
|
||||
- 未改动任何现有组件（Toolbar / TabBar / SignalPanel / PlotView 仍走旧路径），因此**本提交对产品像素零影响**。
|
||||
- 未把 `UiWidget` 接入 `Application`，避免在 P2 之前引入行为差异。
|
||||
|
||||
---
|
||||
|
||||
## 下一步（接手者请从这里开始）
|
||||
|
||||
1. **P2：`PlotViewPaint.cpp` 零行为分片**（9 080 行）
|
||||
- 目标分片：`Paint`（只画）/ `Raster`（缓存与预算）/ `CacheKey`（指纹）/ `Geometry`（面板与命中几何）。
|
||||
- 做法：**机械搬移函数定义**，不改一行逻辑；`PlotViewInternal.hpp` 里的 `pvdetail` 全是 `inline`，跨分片安全。
|
||||
- 判据：`make release` 零警告 + `Target.exe` 体积变化 < 1KB + 场景哈希/像素快照与迁移前一致。
|
||||
- ⚠️ 搬移后务必确认没有残留的 `static` 文件级变量（只在 `PlotViewPaint.cpp` 内可见的辅助函数要一并搬走）。
|
||||
2. **P3：Toolbar 优先**（最小、最容易验证的组件），迁移后跑 `uicheck` + 新旧像素对比。
|
||||
3. 每个阶段单独提交，提交信息写清"改了什么 / 为什么 / 怎么验证"。
|
||||
Reference in new issue
Block a user