# 功能变更 ID: Feature-20260416-0009

> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。

## 基本信息

- ID: Feature-20260416-0009
- 标题: KEY2 使用新布局 API 重构与联动刷新
- 状态：开发中
- 类型：修改
- 级别：L2 中等
- 模块: 测试用例 / Layout API 迁移样例
- 版本 / 分支: 当前工作区
- 环境: Windows + EasyX
- 负责人: Codex 协作修改

## 变更背景

- 背景:
  - `KEY2` 原有布局主要依赖旧 `setAnchor(...)` 语义，无法清晰表达“固定尺寸 + 比例位移”。
  - 32 位位号标签与位按钮分别按各自尺寸参与比例位移，窗口拉伸后会发生错位。
  - 位按钮点击后，下面的十六进制、十进制与二进制显示区刷新链散落在多个回调中，维护成本高且容易漏更新。
- 目标:
  - 把 `KEY2` 改成新布局 API 的首个完整迁移样例。
  - 修复位标签与位按钮 resize 后错位问题。
  - 让位按钮、位操作按钮、配置区按钮共用一条统一的显示刷新链。
- 不做什么：[可选]
  - 不重构 `KEY1 / KEY5`
  - 不引入 `KEY2` 以外的新功能

## 变更内容

- 变更摘要:
  - 重构 `KEY2` 位选择区为“每一位一个小 Canvas 单元”。
  - 使用新布局 API 重排 `KEY2` 的选择区、功能区、数值显示区、二进制显示区与配置区。
  - 抽出统一的 bit 快照、应用、显示刷新链，收口位按钮与功能按钮的联动。
- 新增项：[可选]
  - `KEY2` 内部的布局辅助策略函数
  - `snapshotBits / applyBits / refreshDisplaysWithBits` 这类统一刷新路径
- 修改项：[可选]
  - 32 位位标签与位按钮的组织方式
  - 顶层区域的拉伸策略
  - 一键置 0 / 一键置 1 / 左移 / 右移 / 位取反 / signed toggle 的显示刷新方式
- 删除 / 废弃项：[可选]
  - 废弃旧的“位标签和位按钮分别做比例位移”的选择区组织方式
  - 废弃散在多个回调中的局部显示刷新
- 受影响的文件 / 类 / 函数:
  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/app/z-testDome.cpp)
- 对外 API / 属性变化：[可选]
  - 无框架级 API 变化，属于测试用例迁移

## 行为对照

- 变更前:
  - 32 位位标签与位按钮在窗口拉伸后会发生错位。
  - 位按钮点击后，显示区更新链不统一，后续维护难度高。
  - `KEY2` 的多个区域仍依赖旧锚点表达，窗口拉伸时不够稳定。
- 变更后:
  - 每一位作为独立单元整体位移，位标签与位按钮不再分离漂移。
  - 位按钮、一键置 0/1、位取反、左移、右移、signed toggle 均通过统一刷新链更新显示区。
  - 顶层五个区域在窗口拉伸后继续铺满可用空间，内部小控件保持固定尺寸。
- 兼容性说明：兼容
- 迁移说明：[可选]
  - 这是新布局 API 的示例迁移，不影响其它 `KEY` 入口。

## 验证与落地

- 验证方式:
  - 编译 `z-testDome.cpp /DKEY=2`
  - 编译 `z-testDome.cpp /DKEY=5`
  - 手动验证 `KEY2`：
    - 窗口横向拉伸
    - 位按钮点击
    - 位取反 / 左移 / 右移
    - 一键置 0 / 一键置 1
    - 有符号 / 无符号切换
- 验证结果:
  - 编译级验证通过。
  - GUI 手动验证待本机继续确认。
- 关联 BUG / Fix：[可选]
  - 无单独 BUG 记录，本次属于布局 API 落地后的示例迁移
- Commit:
- PR：[可选]
- 发布版本：[可选]
- 备注：[可选]
  - 当前功能区采用左/中/右固定宽度面板布局；窗口变宽时可稳定铺满，若后续需要进一步适配极窄窗口，再考虑把功能区做成等比分栏。