# Fix-BUG-20251220-0001

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

## 关联信息

- Fix ID: Fix-BUG-20251220-0001
- 关联 BUG ID: BUG-20251220-0001
- 修复目标: 正确支持绘制前设置默认激活页，并在首次绘制时激活对应页面；运行时调用则立即切换，且不崩溃。
- 状态：已完成
- 负责人: 未记录
- 分支 / 版本: master / v2.3.2

## 根因分析

- 根因: `setActiveIndex()` 在设置默认激活时直接调用页签按钮点击回调，但绘制前页签按钮部分内部指针尚未初始化，导致空指针访问。
- 触发条件: 绘制前调用 `TabControl::setActiveIndex()`。
- 为什么之前没发现：[可选] 测试缺失，未覆盖绘制前设置默认激活页的生命周期场景。
- 关键证据：[可选] 最小复现仅需创建 TabControl 并在绘制前调用 `setActiveIndex(0)`。

## 修复方案

- 修复思路: 首次绘制前调用 `setActiveIndex()` 时只记录默认激活索引，不立即调用页签按钮点击回调；在 `TabControl::draw()` 完成基础绘制后再应用默认激活。
- 关键改动:
  - `TabControl::setActiveIndex()` 在首次绘制前仅记录默认激活页索引。
  - `TabControl::draw()` 绘制完成后检查是否为首次绘制、是否设置默认激活页、索引是否合法。
  - 新增成员 `TabControl::IsFirstDraw`，用于判断是否首次绘制。
  - 新增成员 `TabControl::defaultActivation`，用于记录默认激活索引；未设置时为 `-1`。
- 涉及文件 / 类 / 函数:
  - `TabControl.h`
  - `TabControl.cpp`
  - `TabControl::setActiveIndex()`
  - `TabControl::draw()`
- 影响的 API / 行为：[可选] 对外接口不变；内部延迟首次激活流程。
- 关键约束 / 不变量：[可选]
  - 首次绘制前的默认激活只记录，不触发未初始化对象的点击回调。
  - 首次绘制后调用 `setActiveIndex()` 应立即切换激活页。
- 回滚点 / 开关：[可选] 回退默认激活延迟应用逻辑。

## 影响评估

- 影响范围: TabControl 默认激活、首次绘制、运行时程序化切页。
- 兼容性影响：无（对外接口不变）
- 行为变化：有（绘制前设置默认激活页改为首次绘制后应用）
- 性能影响：无明显影响。
- 回归风险:
  - 默认激活索引越界时的行为需要与既有预期保持一致。
  - 开关模式下页签按钮选中态需要与激活页同步。

## 验证结果

- 验证步骤:

1. 创建页签数为 2 的 TabControl。
2. 分别在绘制前调用 `setActiveIndex(0)`、`setActiveIndex(1)`、越界索引。
3. 确认索引 0 / 1 在首次绘制时激活对应页面，按钮处于选中状态。
4. 运行过程中通过 Button 回调调用 `setActiveIndex()`，确认立即切换激活页。
5. 验证未调用 `setActiveIndex()` 时默认不激活任何页面。

- 验证结果: PDF 历史记录标记已修复。
- 回归检查：[可选] 页签点击切换、程序化切换、默认不激活场景、开关模式选中态、页签数量变化与越界索引行为。
- 验证证据：[可选]

## 落地信息

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