StellarX-kaifa/开发记录/功能变更/Feature-20260409-0003-输入事件与遮挡交互调整.md

功能变更 ID: Feature-20260409-0003

适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。

基本信息

• ID: Feature-20260409-0003
• 标题: 输入事件、hover 与遮挡交互调整
• 状态：已完成
• 类型：修改
• 级别：L2 中等
• 模块：Window / Canvas / Button / TextBox / Dialog / TabControl
• 版本 / 分支：master
• 环境：Windows + EasyX + VS2022
• 负责人：Codex 协作修改

变更背景

• 背景:
  • 初始版本中，hover、点击、遮挡与重叠控件之间的事件传递不够稳定。
• 目标:
  • 建立更一致的鼠标事件消费规则，减少穿透、残留 hover 和无意义重绘。
• 不做什么：[可选]
  • 暂不彻底解决“快速划过多按钮偶发一帧双高亮”的底层限制问题。

变更内容

• 变更摘要:
  • 收紧 Button / TextBox / Dialog 的事件消费语义，并补上对话框关闭后及遮挡场景下的 hover 清理。
• 新增项：[可选]
  • Window::dispatchSyntheticMouseMoveToControls(...)
• 修改项：[可选]
  • Button 只在合理命中路径上吞掉鼠标事件
  • TextBox 纯 hover 不再处理
  • 非模态对话框覆盖区域内阻断底层穿透
  • 对话框关闭后补发合成鼠标移动同步 hover
• 删除 / 废弃项：[可选]
  • 大量 hover DEBUG 日志已降噪
• 受影响的文件 / 类 / 函数:
  • Window.cpp
  • Canvas.cpp
  • Button.cpp
  • TextBox.cpp
  • Dialog.cpp
  • TabControl.cpp
• 对外 API / 属性变化：[可选]
  • 无新增公开 API，主要是行为语义变化

行为对照

• 变更前:
  • 遮挡区域 hover/click 可能穿透；对话框关闭后底层 hover 可能残留。
• 变更后:
  • 交互更偏向“命中即消费，关闭后同步清理 hover，遮挡区域不透传”。
• 兼容性说明：部分兼容
• 迁移说明：[可选]
  • 若旧代码依赖非模态对话框下方控件还能收到事件，这种行为已被收紧

验证与落地

• 验证方式:
  • KEY == 2 / 3 / 4 中对按钮、Tab、Table 分页、对话框关闭链做回归
• 验证结果:
  • 主要交互一致性问题已收敛
• 关联 BUG / Fix：[可选]
  • BUG-20260409-0001
  • Fix-BUG-20260409-0001
• Commit:
  • 7f8431a
  • b07a4ec
  • 当前工作区未提交阶段
• PR：[可选]
• 发布版本：[可选]
• 备注：[可选]