docs(share): 补上「为什么是 WindowDialog 而不是 OverlayDialog」的硬理由

查了 Miuix 0.9.3 的源码(下载 sources jar 核对,不是猜):`OverlayDialog` 靠
`MiuixPopupUtils.DialogLayout` 把自己登记进 `LocalDialogStates` / `LocalRootDialogStates`,
而这两个 `staticCompositionLocalOf` **只有 Miuix 的 `Scaffold` 会 provide**
(`basic/Scaffold.kt` 的 Surface 里那层 CompositionLocalProvider)。

本面板的调用点在 `ChatScreen` 那个 `Scaffold` 的**外面**(与附件预览 / 编辑 / 删除三个弹层
同一处)⇒ 换用 `OverlayDialog` 会拿到一个没人读的默认空列表:**不报错、也不显示**,
分享进来会变成「什么都没发生」。这条写进 KDoc,免得后人只看到 W53S 用了 `OverlayDialog`
就顺手把这里改过去(两处调用点的处境不同:那个确认框长在设置页的 Scaffold 里)。

只改注释。验收:./gradlew.bat --console=plain assembleDebug testDebugUnitTest → BUILD SUCCESSFUL,
102 suite / 1278 tests / 0 失败。
This commit is contained in:
AskaEth committed 2026-10-06 18:54:43 +08:00
1 parent b06688f1db
commit 0a43cedea9
1 file changed
+17 -7
@@ -49,13 +49,23 @@ import top.yukonga.miuix.kmp.window.WindowDialog
*
* ## 为什么用 Miuix 的 `WindowDialog`
* 项目里其余四个弹层(编辑 / 删除 / 附件预览 / 图片预览)用的是 Compose 的 `androidx.compose.ui.window.Dialog`
* + Miuix 内容,因为它当年在 Miuix 里找不到可用的弹层控件。Miuix 0.9.3 其实自带两族:
* `top.yukonga.miuix.kmp.overlay.*`(`OverlayDialog` / `OverlayBottomSheet`,在当前组合里当一层浮层)
* 与 `top.yukonga.miuix.kmp.window.*`(`WindowDialog` / `WindowBottomSheet`,真正的弹窗)。
* 本面板用 **window 族**:它与既有那四个弹层是**同一个形态**——独立窗口、自带遮罩、点面板外或按返回键
* 即取消(`onDismissRequest`,这里接的就是「取消」)。overlay 族要求调用方自己在组合里安排浮层的宿主
* (它的 `renderInRootScaffold` 就是为此而生),那会给「分享落地」这段再加一处 DOM 之外的状态,
* 而这里要的只是一次确认,不需要底部面板那种可拖拽的手势。
* + Miuix 内容,因为它当年在 Miuix 里找不到可用的弹层控件。Miuix 0.9.3 其实自带两族(**没有**旧版本的
* `extra.*` 包,别照那个去猜 import):`top.yukonga.miuix.kmp.window.*`(`WindowDialog` /
* `WindowBottomSheet`,真正的弹窗)与 `top.yukonga.miuix.kmp.overlay.*`(`OverlayDialog` /
* `OverlayBottomSheet`,在当前组合里当一层浮层)。
*
* 本面板用 **window 族**,两个理由:
*
* 1. **overlay 族在调用点上是走不通的**(不是偏好,是硬约束):`OverlayDialog` 靠
* `MiuixPopupUtils.DialogLayout` 把自己登记进 `LocalDialogStates` / `LocalRootDialogStates`,
* 而这两个 `staticCompositionLocalOf` **只有 Miuix 的 `Scaffold` 会 provide**(`basic/Scaffold.kt`)。
* 本面板的调用点在 `ChatScreen` 里那个 `Scaffold` 的**外面**(与附件预览 / 编辑 / 删除那三个弹层
* 同一处),拿不到宿主——而它的默认值是一个没人读的空列表,于是**不报错、也不显示**:
* 分享进来会变成「什么都没发生」,正是本项目最忌讳的那种静默失败。(同批的 W53S 用的是
* `OverlayDialog`,因为那个确认框就长在设置页的 `Scaffold` 里——两处调用点的处境不同。)
* 2. 它与既有那四个弹层是**同一个形态**:独立窗口、自带遮罩、点面板外或按返回键即取消
* (`onDismissRequest`,这里接的正是「取消」)。这里要的只是一次确认,不需要底部面板那套
* 可拖拽的手势。
*
* ## 预览与输入框的分工
* 上半是**预览**(图片缩略图 / 文件芯片 / 分享正文),下半是**输入框**(初值就是分享进来的正文,