Files
StellarX-kaifa/开发记录/功能变更/Feature-20260416-0009-KEY2-使用新布局API重构与联动刷新.md
T

3.7 KiB
Raw Blame History

功能变更 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 的显示刷新方式
  • 删除 / 废弃项:[可选]
    • 废弃旧的“位标签和位按钮分别做比例位移”的选择区组织方式
    • 废弃散在多个回调中的局部显示刷新
  • 受影响的文件 / 类 / 函数:
  • 对外 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:[可选]
  • 发布版本:[可选]
  • 备注:[可选]
    • 当前功能区采用左/中/右固定宽度面板布局;窗口变宽时可稳定铺满,若后续需要进一步适配极窄窗口,再考虑把功能区做成等比分栏。