MooTool next-compose:Vault Git 面板的会话级持久化设计与实现(DIFF-246)

原创2026-10-14 15:07:192,289 阅读
文章标签:开发工具桌面应用MCP 服务

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 一个布尔字段,但它牵出的是桌面工具类应用里模态面板状态管理的三层模型,且每一层都能在源码中对应到具体文件:

  1. 状态归属层:gitDialogOpen 从 remember 局部状态提升到 JsonSession / QuickNoteSession(SessionManager.kt),与 Electron 的模块级 jsonVaultSessionState.gitDialogOpen / quickNoteSessionState.gitOpen 一一对应,切页、重建后不丢失;
  2. 渲染边界层:面板 UI 只在该工具 Screen 组合期间按 if (session.gitDialogOpen) 绘制,会话状态跨页存活但不会遮挡其它工具页;
  3. 清理守卫层: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)时以“行为等价 + 测试锁定”为核心手段的典型案例。

登录后查看全文
MooTool