StellarX-kaifa/开发记录/Fix/Fix-BUG-20260217-0001-TabControl-getActiveIndex无激活页返回值修复.md

Fix-BUG-20260217-0001

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

关联信息

• Fix ID: Fix-BUG-20260217-0001
• 关联 BUG ID: BUG-20260217-0001
• 修复目标: TabControl::getActiveIndex() 在页签列表为空或无页签激活时返回 -1，有页签激活时返回对应索引。
• 状态：已完成
• 负责人: 未记录
• 分支 / 版本: master / v3.0.1

根因分析

• 根因: getActiveIndex() 未处理“页签列表不为空但所有页签都未激活”的情况。
• 触发条件: 调用 TabControl::getActiveIndex() 时，页签列表非空且没有任何激活页签。
• 为什么之前没发现：[可选] 测试缺失，未覆盖无激活页但列表非空的返回值场景。
• 关键证据：[可选] 代码分析确认旧逻辑会返回最后一个页签索引。

修复方案

• 修复思路: 增加无激活页兜底逻辑；页签列表为空或遍历后未找到激活页时统一返回 -1。
• 关键改动:
  • 修改 TabControl::getActiveIndex()，在无激活页时返回 -1。
• 涉及文件 / 类 / 函数:
  • TabControl.cpp
  • TabControl::getActiveIndex()
• 影响的 API / 行为：[可选] 修正返回值语义；调用方可可靠用 -1 判断无激活页。
• 关键约束 / 不变量：[可选] 无激活页必须返回 -1，不能返回任意有效索引。
• 回滚点 / 开关：[可选] 回退无激活页兜底返回逻辑。

影响评估

• 影响范围: TabControl 激活页查询、依赖 getActiveIndex() 的业务判断。
• 兼容性影响：无（修复 BUG）
• 行为变化：有（无激活页从错误有效索引变为 -1）
• 性能影响：无明显影响。
• 回归风险: 低；需确认有激活页和空列表场景返回值正确。

验证结果

• 验证步骤:

1. 调用 TabControl::getActiveIndex()，验证页签列表为空时返回 -1。
2. 验证页签列表不为空且所有页签未激活时返回 -1。
3. 验证存在激活页时返回对应索引。

• 验证结果: PDF 历史记录标记已修复。
• 回归检查：[可选] TabControl 默认激活、页签切换、无激活页状态。
• 验证证据：[可选] 无

落地信息

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