breaking(TPopup): 收敛蒙层配置并补齐 1.0.1 升级说明

CONTRIBUTING.md

@@ -186,11 +186,12 @@ CI 显示名按验证（`CI / …`）、生成维护（`Generated / …`）和
 | 内容 | 唯一来源 | 使用与生成方式 |
 |---|---|---|
 | 项目介绍和最短示例 | 根README.md、README_zh_CN.md | 中英文分别维护，包内副本生成 |
-| 安装、主题（含明暗模式）、国际化、FAQ、迁移 | tdesign-site/site/docs/ | 站点直接读取，迁移另生成包内MIGRATION.md |
+| 安装、主题（含明暗模式）、国际化、全局FAQ、迁移 | tdesign-site/site/docs/ | 站点直接读取，迁移另生成包内MIGRATION.md |
 | 贡献规范 | 本文件 | 站点直接读取并适配页面元信息与相对链接 |
 | 站点开发方式 | [tdesign-site/README.md](tdesign-site/README.md) | 其他说明链接到此处 |
 | API | lib中的公开dartdoc注释 | 生成example/assets/api，站点和示例App共用 |
 | 示例 | example/lib中的标注源码 | 生成example/assets/code，站点和示例App共用 |
+| 组件FAQ | tdesign-site/docs/components/<组件>/README.md | 放在生成API入口后，仅补充使用问答，不复制API表或演示区块 |
 | 设计决策与验收 | specs/ | 按组件或长期职责集中维护，过时方案清理；现行用户用法写入用户指南 |
 | 发布流程与记录 | PUBLISH.md及既有CHANGELOG生成入口 | 发布步骤与历史记录分开维护 |
 

specs/components/018-Feedback-Popup/acceptance.md

@@ -29,3 +29,7 @@
 未绑定唯一候选的结果不作为当前通过证明；旧命令与流水由Git历史追溯。
 
 当前待办见 [tasks.md](./tasks.md)；实际执行入口见[贡献规范](../../../CONTRIBUTING.md#组件测试与-ci-回归门禁)。清理不关闭未完成项。
+
+## 1.0.1 蒙层配置源码 breaking 候选
+
+初始基线 develop 3704434f，当前基线 develop 264fc582；独立候选结果、FAQ 修正及 onClick 废弃兼容的双版本复验见 [配置设计验收](./evidence/overlay-final.md)。此前 onTap 兼容别名或 destroyOnClose 分支结果不作为当前候选证据。

specs/components/018-Feedback-Popup/evidence/overlay-final.md

@@ -0,0 +1,41 @@
+# Popup 蒙层配置与使用说明验收
+
+## 候选与范围
+
+基线 develop `264fc58206309039bc63216a88153be30d1ef407`，本轮修订父提交 `410aa8a6e213c4cbb895ec3a9a5f3ca98d13aedd`。本次按 1.0.0 → 1.0.1 整理源码迁移和文档，最终提交以 #1199 的 head 为准；此前版本方向与阶段性文案由 Git 历史追溯，不作为当前发布契约。
+
+TPopupOverlayConfig 仍为 final，推荐使用 onTap，但恢复 onClick 构造参数与只读成员并标记废弃。非空 onTap 优先，否则回退到 onClick；旧成员返回同一有效回调，只触发一次。普通旧构造调用和成员访问继续可编译，废弃提示可能使将提示视为错误的静态检查不通过。库外 extends/implements 与相关 mock 仍需适配，属于明确的源码 breaking；发布版本目标不改变这一兼容性结论。直接构造、const、配置默认值、蒙层通知时机和关闭条件保持。Drawer 仅迁移内部调用，公开 onOverlayClick 不变。动态 getter 与配置快照可能不等价，不能以新增 getter 或 noSuchMethod 绕过 final。
+
+## 使用契约与文档
+
+Popup 组件 API 页签的 FAQ 集中说明升级风险、onTap 替换和工厂组合；全局 FAQ 移除重复详情。API 注释与生成文档明确 show() 创建并立即显示新会话，无需随后 open()；open() 沿用原句柄配置重开，已展示时不重复打开。对照 v1.0.0 的 t_popup_handle.dart 确认固定 options 是既有行为。更换配置通过 show() 创建新会话，不自动关闭旧会话。
+
+不新增 update()、dispose()、宿主 API 或 maintainState，不修改 TPopupOptions/copyWith、Controller 绑定规则和 Popup 生命周期。destroyOnClose 修复、关闭后 State 保留及最终释放说明继续由 #1197 独立交付，不以本 PR 的说明替代其验收。
+
+组件页校验仅允许生成入口后追加 FAQ；继续禁止复制 API 表、额外演示章节、原始演示面板和重复生成入口。贡献规范同步记录组件 FAQ 的维护来源。
+
+## 当前验证
+
+- Flutter 3.32.0 / 3.47.7 各 320 项通过：Popup、Drawer、5 项包外消费者及字体/回归登记检查。消费者覆盖库外继承/实现、旧 onClick 参数及成员可用且产生废弃提示，以及 const 构造和工厂组合可用。
+- 覆盖旧入口单独传入、新入口单独传入、新旧同时传入及显式 null 回退；实际蒙层点击验证只通知一次、通知先于关闭或不关闭，并验证主题颜色合并时回调不丢失。const 构造、默认 null 和有效回调成员读取有正式断言。
+- 两版完整 flutter analyze --no-pub --fatal-infos 零诊断，各 57 份生成 API --check 通过。
+- 站点主题/文档 35 项通过；57 份组件文档映射 360 份生成示例检查通过。新增 FAQ 正反例验证不放开其他页面约束。
+- Popup FAQ 已在本地站点 API 页签预览，截图只保留本地 artifacts/pr1199-faq-preview，不进入仓库。
+
+初次完整分析因 Example 未解析依赖失败；低版隔离快照还缺本地 css2token 包。补齐同候选依赖后重跑完整分析通过，没有修改依赖声明或提交平台生成文件。本轮 Popup 覆盖率高版 531/547（97.07%）、低版 533/547（97.44%），通过 95% 门禁。未运行全包、Golden、真机或 Web release。
+
+当前日志位于本地 artifacts/pr1199-faq-preview/alias-{high,low}-{tests,coverage,analyze,api}.log、alias-site.log；候选输入哈希见 alias-inputs.json。低版使用独立快照和独立 SDK 配置，源文件与当前候选核对。
+
+## Review
+
+本轮生产改动仅恢复 onClick 兼容入口并统一解析有效回调，未改变路由分派、关闭流程、show/open 或 Controller 逻辑。包外消费者测试验证废弃提示与 final 源码风险。FAQ、API、Spec 和测试对源码风险、配置复用及关闭行为的表述一致。未混入生命周期修复，也未增加配置更新能力。保留草稿，人工兼容性评审及最终 head CI 状态另见 PR，暂不合并。
+
+
+## 测试字体维护
+
+新增废弃注释中的“废”触发既有源码字体扫描。补齐 component_demo_glyphs.txt，并使用原 Noto Sans SC 2.004（源 SHA-256 faa6c9df652116dde789d351359f3d7e5d2285a2b2a1f04a2d7244df706d5ea9）与 HarfBuzz 11.4.5 更新共享测试字体。逐个核对原有 1181 个映射字形的轮廓和字宽均未变化；新字体哈希见字体 README。不修改 Golden 基线，最终像素回归以远端 Linux CI 为准。
+
+
+## 文案一致性复核
+
+FAQ 与 PR 开头明确区分 final 的源码不兼容和 onClick 的废弃兼容；更新日志保持二级列表，仅列 API 变更，折叠提醒保留最小升级适配摘录。API 源注释与生成文档已在 1403dbaa 同步，本轮不修改实现或生成 API。站点文档检查 35 项及 57 份组件/360 份示例映射检查通过；日志为 artifacts/pr1199-faq-preview/alias-doc-followup-site.log。双版本功能、静态分析与覆盖率沿用上一节同一实现的验证，不重复声明为本轮重跑。

specs/components/018-Feedback-Popup/plan.md

@@ -26,3 +26,7 @@ bottom 只提供 headerBuilder，center 只提供 closeBuilder；按钮业务回
 4. 结果绑定候选、环境和必要证据，更新 acceptance.md；真实剩余工作只在 tasks.md 维护。
 
 本次文档整理不执行上述实现或候选验收，不据旧命令流水推定当前检查通过。
+
+## 1.0.1 蒙层配置调整
+
+先固定 final/回调兼容及 FAQ，再迁移包内调用、生成文档并验证外部消费者。双 SDK 检查 Popup 功能、默认行为、遮罩分派和静态诊断，作为独立源码 breaking 草稿，不依赖其他未合并 PR。

specs/components/018-Feedback-Popup/spec.md

@@ -37,8 +37,8 @@ Popup 是承载任意内容的基础浮层。小程序基础 Popup 默认只渲
 ### 面板与蒙层
 
 - child、placement、width/height/inset、生命周期和单次 animationDuration 归 TPopupOptions。TPopupThemeData 承载面板背景、圆角、默认尺寸及 barrierColor；不保存同义动画时长或 barrierOpacity。
-- TPopupOverlayConfig 只包括 showOverlay、color、preventTap、closeOnClick、onClick。color 自带 alpha，不再叠乘独立 opacity。默认显示遮罩并拦截背景；未指定色时回退组件 Theme，再到 black54。
-- 可见性与拦截独立。只有可见且拦截的蒙层响应 onClick 和 closeOnClick；穿透时由背景接收事件，不把不可见层当作可点击遮罩。
+- TPopupOverlayConfig 只包括 showOverlay、color、preventTap、closeOnClick、onTap。color 自带 alpha，不再叠乘独立 opacity。默认显示遮罩并拦截背景；未指定色时回退组件 Theme，再到 black54。
+- 可见性与拦截独立。只有可见且拦截的蒙层响应 onTap 和 closeOnClick；穿透时由背景接收事件，不把不可见层当作可点击遮罩。
 - useSafeArea 默认 false，显式 true 按方向避让。top/bottom/center 默认大圆角；left/right 未设置圆角时为全高矩形，显式设置时只作用于内容侧边缘。
 - 单次 animationDuration 优先，未设置为 240ms；不从已删除的 Theme transitionDuration 取值。减少动画等系统环境继续响应。
 
@@ -87,3 +87,16 @@ Popup 是承载任意内容的基础浮层。小程序基础 Popup 默认只渲
 验收标准描述应满足的行为，不表示已执行或通过；执行范围与证据见 [acceptance.md](./acceptance.md)，剩余事项只在 [tasks.md](./tasks.md) 维护。
 
 跨组件配置职责见 [Theme 契约](../../engineering/048-Theme-configuration-contracts/spec.md)，视觉方法见 [Golden 规范](../../engineering/044-Testing-golden-regression/spec.md)。
+
+## 1.0.0 → 1.0.1 蒙层配置调整（源码 breaking）
+
+TPopupOverlayConfig 改为 final，库外不能 extends 或 implements；推荐使用 onTap，保留 onClick 构造参数及成员并标记废弃。非空 onTap 优先，null 时回退到 onClick；内部只保存并触发一个有效回调，旧成员返回同一个有效回调。保留直接构造、const、五项原有配置的默认值、蒙层通知时机与关闭条件，不涉及 TPopupOptions/copyWith、destroyOnClose 生命周期、Controller 或其他 Popup 类型的继承规则。
+
+原因：配置对象负责不可变配置值，业务使用构造与组合；避免未来新增配置成员都要求外部 implements 补齐。final 不保证任意新增必填参数、改默认值或改变行为都兼容，也不等于限制 Popup 的 child/builder/回调扩展。旧动态 getter 每次读取的行为与配置快照不一定等价，handle.open() 沿用创建句柄时的 options，不会应用新配置；更换配置须重新构造 TPopupOptions，通过 TPopup.show() 创建新会话，不承诺活动 Popup 自动响应外部配置变化。
+
+旧 onClick 普通调用和成员访问保持可用并提示废弃；旧继承、implements 以及相关 mock 仍需迁移；Popup 组件文档的 FAQ 说明接口现状、源码迁移影响、组合替代和新配置的实际应用方式，明确 1.0.0 到 1.0.1 的适配范围，不表述其他版本方向；不用新增一个 getter 的转发作为 final 的适配方案。消费者测试验证旧 implements/extends 被诊断、普通 const 构造与业务工厂可用，并覆盖真实遮罩点击和关闭先后。此 PR 独立于命名迁移及 destroyOnClose 修复，按本次 1.0.1 发布范围审查，但 final 限制仍属于源码 breaking，不能视为完全兼容的 patch；保持草稿，暂不合并。
+
+
+show() 创建独立会话并立即显示，不需要随后调用 open()；open() 沿用原句柄创建时的配置，已显示时不重复打开。更换配置通过 show() 创建新会话，不会自动关闭旧会话。该重开行为在 1.0.0 已存在，API 注释与 FAQ 必须区分既有行为和本次源码迁移。本次不新增 update()、dispose()、宿主 API 或 maintainState，也不修改默认值、回调时机或 Controller 绑定规则。
+
+组件 FAQ 在生成 API 入口后维护；文档校验允许该问答区，但仍拒绝复制 API 表、重复生成入口和额外演示章节。全局 FAQ 不重复 Popup 详情。

specs/components/018-Feedback-Popup/tasks.md

@@ -14,3 +14,9 @@
 - [ ] 后续实际交付前，将验收标准绑定最终候选 SHA、SDK 与相关环境，核对受影响结果；本次仅做文档整理，未运行组件、Golden 或设备验收。
 
 已完成的开发步骤和旧 PR 创建过程已清理。原记录的远端 CI/Review 或设备连接状态不作为当前事实；相关事项需以实际证据核对，不能随文档整理关闭。
+
+## 1.0.1 蒙层配置调整
+
+- [x] final 与 onTap 实现、onClick 废弃兼容、调用点迁移及 FAQ 方案。
+- [x] 完成当前候选双版本消费者、功能、文档与严格分析及本地 Review；当前 Popup 覆盖率通过 95% 门禁。
+- [ ] 核对提交后精确 head CI，完成源码兼容风险及发布范围的人工评审；保持草稿，暂不合并。

tdesign-component/example/assets/api/popup_api.md

@@ -9,7 +9,9 @@
 位置参数：`context`
 
 
-每次调用打开独立浮层，可叠加展示；参数与方向不匹配时抛出 `FlutterError`。
+创建独立会话并立即显示，返回 `TPopupHandle`，无需再调用 `TPopupHandle.open`。
+
+重开原会话使用返回句柄的 `TPopupHandle.open`；更换配置需重新调用本方法。多次调用可叠加展示，不会自动关闭旧会话；参数与方向不匹配时抛出 `FlutterError`。
 
 | 名称 | 类型 | 默认值 | 说明 | 必传 |
 | --- | --- | --- | --- | --- |
@@ -311,7 +313,9 @@
 位置参数：`context`
 
 
-打开或重新打开浮层。
+使用创建句柄时的 `options` 打开或重新打开浮层。
+
+不更新配置或创建独立会话；更换配置请调用 `TPopup.show`。
 
 <!-- api-table: details -->
 | 名称 | 类型 | 默认值 | 说明 | 必传 |
@@ -348,7 +352,8 @@
 | --- | --- | --- | --- | --- |
 | closeOnClick | bool? | - | 点击蒙层是否关闭；仅显示蒙层且拦截交互时生效，未指定时为 true。 | 否 |
 | color | Color? | - | 蒙层颜色（含透明度）；未指定时取 `TPopupThemeData.barrierColor`，再回退到 black54。 | 否 |
-| onClick | VoidCallback? | - | 蒙层点击回调；仅显示蒙层且拦截交互时触发，是否关闭由 `closeOnClick` 决定。 | 否 |
+| onClick | VoidCallback? | - | 已废弃，此为兼容入口。请使用 `onTap`；返回实际生效的回调。 | 否 |
+| onTap | VoidCallback? | - | 蒙层点击回调；非空时优先于 `onClick`，仅显示蒙层且拦截交互时触发，是否关闭由 `closeOnClick` 决定。 | 否 |
 | preventTap | bool | true | 是否拦截背景交互。 | 否 |
 | showOverlay | bool | true | 是否显示可见蒙层。 | 否 |
 

tdesign-component/example/test/fonts/README.md

@@ -5,7 +5,7 @@
 缺少 CJK fallback 而把中文渲染成缺字符号。字符清单见
 `component_demo_glyphs.txt`；上游为 Noto Sans SC 2.004，子集工具为
 HarfBuzz 11.4.5，子集 SHA-256 为
-`1cf396734d8d8bd6f81bebc03f9abc16680da03b9bad485564d14e65c0e34235`。
+`980d66bc50a52c95fc5f32ab29faf3aa8f06081093aad3348d8cf5dc12b645a0`。
 它不会打包进 Example 或组件产物。
 
 共享 Demo Golden 工具统一加载 Roboto、Material Icons、Cupertino Icons、

tdesign-component/example/test/fonts/component_demo_glyphs.txt

@@ -1,2 +1,3 @@
 
 &·—…↑→、。〇「」一七三上下不与专且业东丝丢两严个中串临丹为主举久义之乘九也买了予事二于云互五些交产享京亮亳人什仅今介仍从仓他代令以们件价任份企优会传估伸但位低住体何余佛作你使例供依侧侵便促保信修倍倒候借值偏做停偶偿储像允元充先光免兜入全八公六兰共关兴兵其具典兼内册再冒写农冬冲决况冻准减凑几出击函分切划列刘则刚创初删判利别到制刷刻前剩剪副割力办功加务劣动助劳势勇勾勿匀包化北匹区匿十升午半华协单南占卡危即卸厂历压厚原去县参叉及友双反发取受变叠口句另只可台右叶号各合吉同名后向吗君吞否含听启吸呈告员周味命和品哈响哨哪唤售唯商喀善喜嘉器囊四回因团围固国图圆圈在地圳场址均坐块坝坪垂型城域埠基堂堆填境增声壳处备复夏外多大天央失头奇契奔奖套女好如妥始姓委威娇媒子字存孜学它守安完宏官定宝实宫宵家容宽宿密富寒察寸对导封射将小少尔尚尝就尺尽尾局层居屉屏展属山岗岭岳峰崇嵌州巢工左差己已巴市布师带帧帮常幂幕干平年并幽广庄庆序库应底度康延建廿开异弃式引张弧弱弹强归当录形彩影往径待很得御循微德徽心必快忽态性总恒恢恩息恰悬悲情惊惯意感慎慢懒成我或截户所扁手才打托扣执扩扫扰批找承技把投抗折抚抛护报抵抹抽拆拇拉拍拒拖拟拥拦拨择括拷拼拽拿持挂指按挡挤捕换据捷掉排接控推描提插揭搜携摄撑撒播操支收改放故效敛散数整文斑斥断斯新方施旋族无既日旦旧早时昆昌明易星映春是显晋晚普景暂暑暗暮暴曲更替最月有朋服朗望朝期未末本术机杂权束条来杭松板极构析林枚果架柄某染查柱栅标栈栏树校样核根格桂框案桌档桥检棒楚槽模横樽次欢款止正此步武死殊残段毁母每比毕毫气水永求汉汕江池污沙没沧河治沿法泛泡波注洁洛津洲活派流浅浈测济浏浙浮海消涉润淀淡深混添清渐渡港渲游湖湘源溢溪滁滑滚满滤滨漂演潮澳激火灯灰灵点烁热焦然照父片版牌物特状独猜率环现珠理琴甘生用田由电男画界留略登白百的盐监盒盖盘目直相省看真着瞬知矩短石码础硬确碍碰磁示祖神禁福离秀私秋种秒积称移程稳稿空穿突窄窗立竖站端符第等策筛签简算管箭箱籍类粒粗粤精糕糟系素索紧累红约级纯纳纵纹线组细织终经绑结绕绘给络绝统继续维综绿缀缓编缘缩缺罄网罗罩置翻老考者而耦聊职联聚肃肤背胶能脉脑脚腊腾自至致航般舱色节芒花若英范荆草荐莞莫获菊菜营落著蒙蓟薄藏虑虚虽蚌蛇行衔街补表被裁装裹西要覆见观规视览觉角解触言警计认让议讯记许设证评识诊词译试诚话询该详语误说请读课调谨谷象贝负责败货质购贯贴贵费资赋赖赣赤走起超越足跑距跟跨路跳踪身轨转轮轴轻载较辅辑输边达迁过运近返还这进远连迟迪迭述追退送适逃逆选透逐递途通速造逸逻遇遍道遮遵避那邮邻部郴都鄂配醒采释里重量金针钟钮钳银铺链销锁错锚键锯镜长门闪闭问闰间阅阈阜队阱防阳阴阵阶阻阿附际陈降限除险陷隆随隐隔隙障雄集雨雪零需霜露青静非靠面鞍音韶页顶项顺须顿预领频颗题颜额风食饰馈首香马驱驻验骤骨高魔鸡麓黄黑默鼠齐齿龄龙（），：；？～
+废

tdesign-component/lib/src/components/drawer/t_drawer.dart

@@ -124,7 +124,7 @@ TDrawerHandle showTDrawer(
         showOverlay: showOverlay,
         closeOnClick: closeOnOverlayClick,
         color: showOverlay ? null : Colors.transparent,
-        onClick: onOverlayClick,
+        onTap: onOverlayClick,
       ),
       destroyOnClose: destroyOnClose,
       useSafeArea: useSafeArea,

tdesign-component/lib/src/components/popup/_popup_route.dart

@@ -191,7 +191,7 @@ class _PopupNavigatorRoute<T> extends PopupRoute<T> {
 
   void _handleOverlayTap() {
     final overlay = options.overlayConfig;
-    overlay.onClick?.call();
+    overlay.onTap?.call();
     if (overlay.effectiveCloseOnClick) {
       onCloseWithTrigger(TPopupTrigger.overlay);
     }

tdesign-component/lib/src/components/popup/t_popup.dart

@@ -37,7 +37,9 @@ final class TPopup {
   // 私有构造器：工具类仅暴露静态方法，无外部调用，标记为覆盖率例外（不可达死代码）。
   const TPopup._(); // coverage:ignore-line
 
-  /// 每次调用打开独立浮层，可叠加展示；参数与方向不匹配时抛出 [FlutterError]。
+  /// 创建独立会话并立即显示，返回 [TPopupHandle]，无需再调用 [TPopupHandle.open]。
+  ///
+  /// 重开原会话使用返回句柄的 [TPopupHandle.open]；更换配置需重新调用本方法。多次调用可叠加展示，不会自动关闭旧会话；参数与方向不匹配时抛出 [FlutterError]。
   ///
   /// [context] 用于查找 [Navigator] 并获取局部主题。
   ///
@@ -107,7 +109,7 @@ final class TPopup {
       color: overlay.color ?? themeColor,
       preventTap: overlay.preventTap,
       closeOnClick: overlay.closeOnClick,
-      onClick: overlay.onClick,
+      onTap: overlay.onTap,
     );
   }
 }