MooTool next-compose:Vault Git 面板的会话级持久化设计与实现(DIFF-246)
MooTool next-compose:Vault Git 面板的会话级持久化设计与实现(DIFF-246)
本文基于 MooTool 的 next-compose(JetBrains Compose for Desktop)版本中的 DIFF-246 差异文档,详解 Vault Git 面板的打开状态如何从 Compose 局部 remember 状态升级为会话级字段(gitDialogOpen),使其在主窗切页、分离窗口重建等场景下保持稳定,并与 Electron 版 JsonVaultPanel / QuickNoteTool 的模块级会话状态实现行为对齐。读完本文,你可以理解桌面工具类应用中“模态面板状态跨 UI 生命周期持久化”的典型建模方式,以及配套的切页清理守卫机制与测试验证手段。
1. 问题背景:局部 remember 状态会随组件卸载而丢失
在 Compose for Desktop 中,一个工具页(如 JSON 编辑器、随手记)在主窗侧边栏切换到其它工具时,对应的 *Screen 组合会被整体卸载;再切回来时重新组合。如果 Git 面板的打开状态放在局部 remember { mutableStateOf(false) } 中,那么:
- 切走一次页面,Git 面板的打开状态就被重置为
false; - 用户刚打开面板准备执行提交/推送,切到别的工具看一眼再回来,面板就“消失”了;
- 分离窗口(detach)场景下问题更明显:主窗中该工具的位置变成一个占位,占位销毁/重建的过程中若顺手清理了面板状态,分离窗里的 Git 面板也会被误关。
而 Electron 版本自始就采用模块级会话状态解决这个问题。以 JsonVaultPanel.tsx 为例,gitDialogOpen 是 JsonVaultSessionState 类型的一个字段,并被保存在组件外的模块级变量 jsonVaultSessionState 中:
type JsonVaultSessionState = {
nodes: JsonVaultNode[]
selectedEntry: SelectedEntry | null
selectedPath: string
savedContent: string
expanded: Set<string>
gitDialogOpen: boolean // Git 面板打开状态,模块级持久
textAction: TextAction
moveOpen: boolean
moveTarget: string
contextMenu: { entry: SelectedEntry; left: number; top: number } | null
query: string
includeContent: boolean
sort: 'name' | 'modified'
vaultRootKey: string
}
let jsonVaultSessionState: JsonVaultSessionState = {
nodes: [],
selectedEntry: null,
selectedPath: '',
savedContent: '',
expanded: new Set(),
gitDialogOpen: false,
// ...
}
组件挂载时以 useState(jsonVaultSessionState.gitDialogOpen) 从模块级状态回填初始值,卸载时通过 effect 把最新值写回。因此切到其它工具、React 卸载 UI 后,模块级会话不变,回到 JSON 页时 Git 面板保持打开。随手记侧的 QuickNoteTool.tsx 同理,QuickNoteState 持有 gitOpen 字段并由模块级 quickNoteSessionState 保持。
DIFF-246 的目标就是把 next-compose 的 Vault Git 面板状态对齐到这一行为。
2. 核心改动:gitDialogOpen 成为会话字段,替代 remember
DIFF-246 的核心行为描述是:JsonSession.gitDialogOpen、QuickNoteSession.gitDialogOpen 替代 Compose remember 局部状态。
2.1 会话字段定义
两个会话类都定义在 SessionManager.kt 中。JsonSession 中的字段:
class JsonSession {
val editor = EditorBuffer(SAMPLE_JSON)
// ...
var historyOpen: Boolean = false
var gitDialogOpen: Boolean = false // Vault Git 面板打开状态(L145)
var className: String = "Root"
var pathPickerOpen: Boolean = false
var pathPickerSelection: String = ""
// ...
}
QuickNoteSession 中的字段(SessionManager.kt):
class QuickNoteSession {
// ...
var historyOpen: Boolean = false
var gitDialogOpen: Boolean = false // 随手记的 Git 面板状态
var documentInfoPath: String = ""
// ...
}
会话对象由 SessionManager 统一管理(按 ToolId 缓存),其生命周期远长于任何单个 Screen 组合,因此切页、重建组合都不会丢失 gitDialogOpen。
2.2 打开、渲染与关闭面板
面板的打开入口在 JsonScreen.kt 的两处:工具栏按钮和 Vault 侧栏的 Git 按钮,都是直接写会话字段并触发刷新:
onGit = { session.gitDialogOpen = true; refresh() } // JsonToolbar / VaultPane 两处
面板本身以 if (session.gitDialogOpen) 条件渲染 VaultGitDialog(JsonScreen.kt):
if (session.gitDialogOpen) {
VaultGitDialog(
container = container,
title = container.t("json.git.title"),
defaultMessage = container.t("json.git.defaultMessage"),
root = container.jsonVault.root(),
onDismiss = { session.gitDialogOpen = false; gitCountRev++; refresh() },
onFlush = {
jsonGitFlushBeforeAction(container, session, monitor) { session.vaultConflict = it }
},
onVaultRefresh = { /* 刷新 Vault 树并处理外部变更 */ },
onGitStatusChanged = { gitCountRev++; refresh() },
)
}
随手记侧的结构完全对称:QuickNoteScreen.kt 的 GitActionButton 点击后 session.gitDialogOpen = true; refresh(),if (session.gitDialogOpen)(QuickNoteScreen.kt)时渲染 Git 面板,onDismiss 中将其置回 false 并递增 gitCountRev 刷新徽标计数。
这里有一个值得注意的细节:面板的绘制仍然只发生在 JsonScreen / QuickNoteScreen 组合期间。也就是说,会话字段负责“状态不丢”,而 UI 只在该工具页挂载时读取该字段决定画不画遮罩。这与 Electron 版“遮罩随组件挂载/卸载,但状态存模块级”的模型完全一致——切到其它工具页时,Git 面板不会挡在别的工具前面。
2.3 与焦点策略、Vault 作用域清理的联动
因为 Git 面板是模态遮罩,它参与编辑器的焦点判定。JsonEditorFocusPolicy.kt 中:
if (session.findOpen || session.historyOpen || session.pathPickerOpen || session.gitDialogOpen) return false
即 gitDialogOpen 为 true 时编辑器不获焦(QuickNoteEditorFocusPolicy.kt 中随手记同理)。这也意味着该字段不仅影响“画不画面板”,还参与焦点策略,必须放在会话层统一管理。
另一方面,当 Vault 根目录发生切换等“Vault 作用域变更”时,Git 面板属于该作用域内的一次性 UI 状态,需要被显式清理。JsonSession.resetVaultScopedOverlays()(SessionManager.kt):
fun resetVaultScopedOverlays() {
gitDialogOpen = false
vaultConflict = null
vaultDeleteConfirmPath = ""
vaultContextMenuPath = ""
pathPickerOpen = false
// ...
}
QuickNoteSession.resetVaultScopedOverlays()(SessionManager.kt)同样把 gitDialogOpen 置回 false。这划清了边界:切页不清、根目录变了才清。
3. 两条配套守卫:切页清理与分离占位守卫
DIFF-246 的行为条款还引用了两条相邻差异,它们共同构成“何时该清理、何时绝不清理”的完整规则。
3.1 主窗切页:JSON/随手记的模态会话字段保留(DIFF-261)
早期 DIFF-232 曾要求离开 JSON/随手记页时关闭模态遮罩(防止 pathPickerOpen 等残留导致返回时意外弹层)。DIFF-261 在对照 Electron 会话模型后修正了这一策略:JsonSession.dismissModalOverlays / QuickNoteSession.dismissModalOverlays 改为 no-op,不再清空 Git、历史、JSONPath 选择器、Vault 对话框、右键菜单路径等字段;其它工具(HTTP、Host、图片等)仍按原策略在切页时关闭模态。
这一差异直接体现在 ToolModalOverlays.kt:
/**
* Electron `jsonSessionState` / `jsonVaultSessionState` 在切工具时保留 Git、历史、JSONPath 选择器、
* `inputConversion`/`conversionInput`、结果对话框与 Vault 对话框等;遮罩仅在工具页挂载时绘制,切走不会误挡其它页。
*/
internal fun JsonSession.dismissModalOverlays() = Unit
/** 对照 Electron `quickNoteSessionState`:切工具不重置 Git / 历史 / 文档信息 / Vault 操作对话框。 */
internal fun QuickNoteSession.dismissModalOverlays() = Unit
internal fun HttpSession.dismissModalOverlays() {
historyOpen = false
curlOpen = false
saveOpen = false
deleteConfirm = false
}
对比很清晰:JSON/随手记的清理函数是空实现,而 HttpSession 等其它工具仍逐项清位。JsonScreen / QuickNoteScreen 依旧注册了切页清理钩子(JsonScreen.kt):
DismissModalOverlaysOnDispose(container, ToolId.Json) { session.dismissModalOverlays() }
保留调用点(而非删掉调用)的好处是统一了所有工具页的生命周期接入方式,JSON/随手记只是“回调为空”。
3.2 分离占位销毁:!isDetached 守卫(DIFF-244)
第二个场景更隐蔽:当某工具被分离成独立窗口后,主窗中该工具的位置是占位。占位被销毁时,DisposableEffect 的 onDispose 同样会触发切页清理——如果此时执行清理,就会把分离窗里仍应显示的 Git 面板、JSONPath 选择器等共享会话状态清掉。
DIFF-244 为此引入了统一守卫 ToolModalLifecycle.kt:
/** 主窗因分离销毁占位时不应执行切页清理;分离窗关闭会先 reattach,此时 `isDetached` 为 false。 */
internal fun shouldRunToolLeaveCleanup(isDetached: Boolean): Boolean = !isDetached
/**
* 离开工具页(主窗切页或关闭分离窗)时执行清理;主窗因分离而销毁占位时不执行,避免误清共享会话。
* 分离窗关闭会先 [SessionManager.reattach],`isDetached` 为 false 后仍会执行。
*/
@Composable
internal fun DismissModalOverlaysOnDispose(
container: AppContainer,
toolId: ToolId,
onDismissUnlessDetached: () -> Unit,
) {
OnToolLeaveUnlessDetached(container, toolId, onDismissUnlessDetached)
}
@Composable
internal fun OnToolLeaveUnlessDetached(
container: AppContainer,
toolId: ToolId,
onLeave: () -> Unit,
) {
DisposableEffect(toolId) {
onDispose {
if (shouldRunToolLeaveCleanup(container.sessionManager.isDetached(toolId))) {
onLeave()
}
}
}
}
分离状态本身由 SessionManager 维护(SessionManager.kt):
fun detach(toolId: ToolId) {
if (!toolId.detachable) return
_detached.value = _detached.value + toolId
bump()
}
fun reattach(toolId: ToolId) {
_detached.value = _detached.value - toolId
bump()
}
fun isDetached(toolId: ToolId): Boolean = toolId in _detached.value
两个方向的生命周期由此闭环:
- 主窗切页:
isDetached为false,清理回调执行;对 JSON/随手记而言回调是 no-op,gitDialogOpen保留,回到该页时 Git 面板恢复; - 主窗因分离销毁占位:
isDetached为true,清理回调整体跳过,分离窗中的 Git 面板不受影响; - 关闭分离窗:流程上先执行
reattach把工具重新挂回主窗,此刻isDetached已为false,清理回调照常执行,状态机不出现“永不恢复分离”的悬挂。
4. 验证:单元测试与执行方式
DIFF-246 给出的验证方式在 ToolModalOverlaysTest.kt 中有直接对应。JSON 用例先置位一组会话字段,调用 dismissModalOverlays() 后断言它们全部保留:
@Test
fun json_dismissModalOverlays_keeps_session_modals_for_electron_parity() {
val session = JsonSession()
session.pathPickerOpen = true
session.pathPickerSelection = "$.items[0]"
session.historyOpen = true
session.gitDialogOpen = true
session.vaultDeleteConfirmPath = "a.json"
session.vaultContextMenuPath = "b.json"
session.dialogTitle = "title"
session.conversionMode = "xml"
session.conversionInput = "<a/>"
session.dismissModalOverlays()
assert(session.pathPickerOpen)
assertEquals("$.items[0]", session.pathPickerSelection)
assert(session.historyOpen)
assert(session.gitDialogOpen)
// ...其余字段逐项断言保留
}
随手记用例(quickNote_dismissModalOverlays_keeps_session_modals_for_electron_parity)对 historyOpen / gitDialogOpen / documentInfoPath / vaultContextMenuPath / dialogMode / dialogTarget 做同样断言;反向用例则验证其它工具的清理仍然生效,例如 http_dismissModalOverlays_clears_transient_dialogs 断言 HttpSession 的 historyOpen / curlOpen / saveOpen / deleteConfirm 全部被清位。
执行方式(与文档一致,适用于本地 Gradle 环境):
./gradlew :composeApp:desktopTest --offline
5. 小结:一个字段背后的三层状态管理
DIFF-246 本身只涉及 gitDialogOpen 一个布尔字段,但它牵出的是桌面工具类应用里模态面板状态管理的三层模型,且每一层都能在源码中对应到具体文件:
- 状态归属层:
gitDialogOpen从remember局部状态提升到JsonSession/QuickNoteSession(SessionManager.kt),与 Electron 的模块级jsonVaultSessionState.gitDialogOpen/quickNoteSessionState.gitOpen一一对应,切页、重建后不丢失; - 渲染边界层:面板 UI 只在该工具
Screen组合期间按if (session.gitDialogOpen)绘制,会话状态跨页存活但不会遮挡其它工具页; - 清理守卫层:
DismissModalOverlaysOnDispose统一在!isDetached时才执行清理(ToolModalLifecycle.kt),JSON/随手记的清理回调为 no-op(ToolModalOverlays.kt),Vault 根目录变更时则由resetVaultScopedOverlays()显式复位。
配套差异可延伸阅读:DIFF-244 的切页关模态 !isDetached 守卫(244-dismiss-modals-unless-detached.md)、DIFF-261 的 JSON/随手记切页保留模态会话(261-json-quicknote-modal-session-on-tool-switch.md)。整套设计的收益是:用户把 Git 面板打开做提交准备、中途切页甚至分离窗口后回来,面板仍停在原处——这正是跨技术栈对齐(Compose 对齐 Electron)时以“行为等价 + 测试锁定”为核心手段的典型案例。