StellarX-kaifa/开发记录/Fix/Fix-BUG-20251209-0001-TabControl由不可见设置为可见时绘制错乱.md

Fix-BUG-20251209-0001

适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。

关联信息

• Fix ID: Fix-BUG-20251209-0001
• 关联 BUG ID: BUG-20251209-0001
• 修复目标: TabControl 由不可见变为可见时，仅绘制激活页；无激活页时不绘制任何页，避免页面重叠和脏帧。
• 状态：已完成
• 负责人: 未记录
• 分支 / 版本: master / v2.3.2

根因分析

• 根因: TabControl::setIsVisible(true) 对所有页签 / 页面统一传播 true 并置脏，导致恢复可见后本应不可绘制的非激活页也进入绘制流程。
• 触发条件: 执行 setIsVisible(false) 后再执行 setIsVisible(true)。
• 为什么之前没发现：[可选] 缺少“隐藏 -> 显示”回归用例，尤其缺少“多个页面但只允许激活页绘制”的断言。
• 关键证据：[可选] PDF 历史记录明确将疑似位置定位到 TabControl::setIsVisible() 与 show 状态传播。

修复方案

• 修复思路: TabControl 可见性向页面传播时按激活状态过滤；显示时只允许激活页可见，隐藏时所有页都不可见。
• 关键改动:
  • TabControl.cpp::setIsVisible() 在参数为 true 时，根据激活页判定对子页面传递 true / false。
  • 参数为 false 时，对所有页面传递 false。
  • 绘制入口可选择增加“仅绘制激活页”的防御性约束。
• 涉及文件 / 类 / 函数:
  • TabControl.cpp
  • TabControl::setIsVisible()
• 影响的 API / 行为：[可选] 对外 API 无变化；行为层面修正错误绘制。
• 关键约束 / 不变量：[可选] 任意时刻可参与绘制的页面集合最多只有一个激活页。
• 回滚点 / 开关：[可选] 回退 TabControl 页面可见性传播逻辑。

影响评估

• 影响范围: TabControl 隐藏 / 显示、页面激活状态、页面绘制链路。
• 兼容性影响：无（纠错式兼容）
• 行为变化：有（非激活页不再随 TabControl 显示而被绘制）
• 性能影响：无负面影响，减少非激活页绘制后预期更优或持平。
• 回归风险:
  • 如果激活判定逻辑异常导致“无激活页”，恢复显示后会表现为空白页；该行为符合修复目标。
  • 如果外部代码错误依赖非激活页仍可见，可能观察到行为差异。

验证结果

• 验证步骤:

1. 创建含不少于 2 个页的 TabControl，并设置激活页为 0。
2. 调用 setIsVisible(false)，再通过事件调用 setIsVisible(true)。
3. 确认仅激活页显示，非激活页不绘制、不重叠。
4. 切换激活页后重复隐藏 / 显示，确认仍只绘制当前激活页。
5. 验证无激活页场景，确认不绘制任何页。

• 验证结果: PDF 历史记录标记已修复。
• 回归检查：[可选] 嵌套容器可见性、裁剪、鼠标事件命中、布局刷新、脏标记 / 快照重绘路径。
• 验证证据：[可选]

落地信息

• Commit: 0c1cf2938f
• PR：[可选] git
• 发布版本: v2.3.2
• 备注: 来源原始 Fix 记录未包含 -XXXX 后缀，入库时按 BUG ID 补充为 Fix-BUG-20251209-0001。