[RSS1102]

🤔 这个 PR 的性质是？

勾选规则:
1.只要有新增参数，就勾选”新特性提交“
2.只修改内部bug，未新增参数，才勾选”日常 bug 修复“
3.其他选项视具体改动判断

• 日常 bug 修复
• 新特性提交
• 文档改进
• 演示代码改进
• 组件样式/交互改进
• CI/CD 改进
• 重构
• 代码风格优化
• 测试用例
• 分支合并
• 其他

🔗 相关 Issue

关联 #1148 的 API 审查；按组件职责拆分交付。

💡 需求背景和解决方案

• 理由
  • 蒙层回调表示点击事件，使用 onTap；显隐变化继续由 onVisibleChange 通知。
  • 配置类通过构造和组合封装业务，收敛外部继承/实现边界。
• 改动
  • TPopupOverlayConfig 改为 final；新增 onTap，保留 onClick 参数及只读成员并标记废弃。
  • 非空 onTap 优先，否则回退到 onClick；只通知一次，原默认值、回调时机和 Controller 绑定规则不变。
  • API 与 Popup FAQ 补齐 1.0.0 → 1.0.1 适配和 show() / open() 区别；destroyOnClose 仍由 breaking(TPopup): 修复 destroyOnClose 的关闭销毁与状态保留 #1197 独立处理。
• 风险
  • final 会使旧继承、implements 及相关 mock 无法编译，需改用构造或组合；仍属于源码 breaking。
  • 普通旧 onClick 调用仍可编译，但废弃提示可能影响严格静态检查；动态 getter 与配置快照也不保证等价。

验证：本地 Flutter 3.32.0 / 3.47.7 各 320 项回归、严格分析及各 57 份 API 检查通过，站点 35 项通过；当前 head CI 全部成功，含 Linux Golden 和平台构建。构建通过不代表真机验收。

Spec/验收 · Popup FAQ。保持草稿，暂不合并。

📝 更新日志

• breaking(TPopup): 收敛蒙层配置继承规则。
  • TPopupOverlayConfig 改为 final，库外继承/实现及相关 mock 需改用直接构造或组合。
• feat(TPopup): 新增蒙层点击回调 onTap，兼容旧入口。
  • onClick 参数及成员保留并标记废弃；非空 onTap 优先，否则沿用 onClick，只触发一次。默认行为和回调时机不变。

1.0.0 → 1.0.1 升级提醒（存在源码不兼容变化）

• 配置类改为 final，库外不能再 extends 或 implements；已有业务子类和相关 mock 需改为直接构造或通过工厂组合。
• onClick 构造参数及成员保留并标记废弃，旧调用仍可编译使用；推荐改用 onTap。两者同时传入时，非空的 onTap 优先，只触发一次；旧 onClick 成员返回实际生效的回调。

完整适配说明与示例见 Popup FAQ。

• 本条 PR 不需要纳入 Changelog

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项。⚠️

• 标题遵循 Conventional Commits 格式：type(<scope>?): 修改描述。
  示例：fix(TBottomTabBar): 修复 iconText 模式底部溢出
• “相关 Issue”处带上修复的 Issue 链接或无关联 Issue
• 已添加对应的 Spec 链接，或已由 Review 确认本次改动无需 Spec
• 相关文档已补充或无须补充

[github-actions]

Web Demo

• web-example

APK 下载

• 下载 APK（ZIP，解压后安装）