StellarX-kaifa/开发记录/模块/Module-20260416-0005-布局策略公开API落地.md

# 新增功能模块 / 模块重构

> 适用场景：新增模块、重大模块重构、核心架构能力演进。
> 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。

## 基本信息

- 模块 ID：Module-20260416-0005
- 模块名称: 布局策略公开 API 落地
- 状态：开发中
- 类型：架构演进
- 所属系统 / 子系统: GUI 框架 / Layout API
- 版本 / 分支: 当前工作区 / 下一开发阶段
- 环境: Windows + EasyX
- 负责人: Codex 协作修改

## 背景与目标

- 背景:
  - 第一阶段与第二阶段已经把内部布局模型收口到 `LayoutSpec / LayoutCapability / AxisSizePolicy / AxisAlignPolicy`。
  - 外部调用层仍主要依赖 `setLayoutMode(...)` 与 `setAnchor(...)`，无法直接表达“固定尺寸 + 比例位移”“固定尺寸 + 居中”这类语义。
  - `KEY2` 顶部位选择区就是典型例子：旧双锚点语义不足，导致按钮与标签 resize 后错位，且难以继续扩展。
- 当前痛点:
  - 外部用户无法直接设置 `AxisSizePolicy / AxisAlignPolicy`。
  - 旧 demo 继续依赖旧锚点入口，验证成本高，迁移路径不清晰。
  - 新旧 API 混用规则若不写清，后续容易再次回到“旧 anchor 硬凑新布局”的状态。
- 目标:
  - 将当前内部布局策略正式开放为公开 API。
  - 明确新旧 API 混用规则与对外可见语义。
  - 用 `KEY2` 作为新布局 API 的首个迁移样例。
- 非目标：[可选]
  - 不统一 `Dialog` 旧 synthetic `WM_MOUSEMOVE` 机制。
  - 不实现 `Table` 内部局部重绘体系。
  - 不实现 Tooltip 智能选位。
  - 不扩展 `Table` 纵向拉伸和字体缩放。

## 模块边界

- 职责:
  - 对外开放按轴设置布局规格的最小 API。
  - 固化新旧 API 的混用规则与默认行为。
  - 提供首个迁移样例，验证新 API 可表达旧场景中“旧 anchor 无法清晰表达”的布局。
- 不负责什么:
  - 不开放 `LayoutCapability` 的通用外部修改接口。
  - 不改变控件内部硬能力边界。
  - 不把所有旧 demo 一次性全部迁完。
- 外部依赖:
  - `Control / Canvas / TabControl / Table / Label / TextBox`
  - `z-testDome.cpp`
- 对外能力 / API:
  - `setHorizontalLayoutSpec(...)`
  - `setVerticalLayoutSpec(...)`
  - `setHorizontalAnchors(...)`
  - `setVerticalAnchors(...)`
  - `setHorizontalSizePolicy(...)`
  - `setVerticalSizePolicy(...)`
  - `setHorizontalAlignPolicy(...)`
  - `setVerticalAlignPolicy(...)`
  - `getHorizontalLayoutSpec()`
  - `getVerticalLayoutSpec()`
- 关键数据 / 状态:
  - `layoutSpec`
  - `layoutMode`
  - `layoutCapability`
  - `localx / localy / localWidth / localHeight`
  - `x / y / width / height`

## 设计说明

- 核心流程:
  - 外部通过新 API 直接写入水平轴 / 垂直轴布局规格。
  - 新 API 被调用后，控件自动切到 `AnchorToEdges` 布局模式。
  - 运行时统一解算继续以 `layoutSpec` 为唯一依据。
- 关键对象 / 类关系:
  - [`Control.h`](D:/programming/imGUI-easyX/imGui-easyX/Control.h)：公开布局策略 API 的对外入口。
  - [`Control.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Control.cpp)：新 API 的实现、新旧 API 映射共存规则。
  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)：`KEY2` 迁移示例与验证入口。
- 生命周期:
  - 新 API 只影响运行态布局策略，不自动提交设计基线。
  - 设计基线仍由显式提交路径或控件内部受控路径维护。
- 事件 / 渲染 / 数据流：[按模块类型填写]
  - 新 API 不改变事件分发与局部重绘主链。
  - 只是改变布局规格输入层与解算参数来源。
- 关键不变量:
  - 新旧 API 混用时，后调用者生效。
  - 旧 API 仍保留兼容，但只覆盖新模型的有限子集。
  - 公开布局 API 不得自动回写 `local*`。
- 降级 / 回退策略：[可选]
  - 非法组合继续沿用现有降级规则，并输出最小必要日志。
  - 若后续回退，只需回退 `Control` 中新增 API 与 `KEY2` 迁移代码，不影响第二阶段主线。

## 实现与影响

- 关键实现点:
  - 在 `Control` 层开放最小够用的布局策略 API。
  - 新 API 调用后自动切换到 `AnchorToEdges`。
  - 保留 `setAnchor(...)` 与旧 getter，不破坏兼容路径。
  - 以 `KEY2` 位选择区、功能区、显示区和配置区作为迁移样例，验证新 API 的可用性。
- 涉及文件 / 类 / 函数:
  - [`Control.h`](D:/programming/imGUI-easyX/imGui-easyX/Control.h)
  - [`Control.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Control.cpp)
  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
- 兼容性影响:
  - 兼容旧 `setAnchor(...)` 调用。
  - 新 API 为新增能力，不影响现有二进制接口使用方式。
  - 混用时以最后一次设置为准。
- 性能影响:
  - 布局解算主逻辑不变，性能影响可忽略。
  - `KEY2` 迁移后控件层次变多，但仍处于测试用例范围。
- 风险点:
  - `KEY2` 迁移后可能暴露旧 demo 中原本被旧锚点语义掩盖的布局问题。
  - 若后续没有补使用说明，外部调用仍可能继续滥用旧锚点入口。

## 测试与验证

- 测试范围:
  - `Control` 新公开布局 API 编译级验证
  - `KEY2` 迁移后的布局与显示联动
  - `KEY5` 回归，确认新 API 未破坏第二阶段主线
- 验证步骤:

1. 编译 `Control.cpp`
2. 编译 `z-testDome.cpp /DKEY=2`
3. 编译 `z-testDome.cpp /DKEY=5`
4. 手动回归 `KEY2` 位选择区、功能区、显示区与配置区的 resize 和联动行为

- 验证结果:
  - 编译级验证通过。
  - GUI 手动回归待本机继续确认。
- 已知限制 / 遗留问题：[可选]
  - `Dialog` 旧 synthetic `WM_MOUSEMOVE` 机制暂未统一。
  - `Table` 内部局部重绘体系暂未实现。
  - resize 过程中若开启高频 console 日志，可能出现一帧视觉延迟；当前判断属于调试态 I/O 现象，不作为 bug 处理，后续可在官网或 API 文档中注明。

## 落地信息

- 关联功能变更 ID：[可选]
  - `Feature-20260416-0009`
- 关联 BUG / Fix：[可选]
  - [Module-20260415-0004-布局系统第二阶段验收与封口.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260415-0004-布局系统第二阶段验收与封口.md)
- Commit:
- PR：[可选]
- 发布版本：[可选]
- 相关文档：[可选]
  - [Module-20260410-0002-锚点与布局系统第一阶段重构.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260410-0002-锚点与布局系统第一阶段重构.md)
  - [Module-20260415-0004-布局系统第二阶段验收与封口.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260415-0004-布局系统第二阶段验收与封口.md)