# 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: 0c1cf2938f0d6c5684eeb318f17a8443e0c8cf5a
- PR：[可选] git
- 发布版本: v2.3.2
- 备注: 来源原始 Fix 记录未包含 `-XXXX` 后缀，入库时按 BUG ID 补充为 `Fix-BUG-20251209-0001`。