MooTool DIFF-300:JSON 历史恢复与查找替换 copy 反馈对齐 Electron 的实践指南

原创2026-10-14 18:40:122,234 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool DIFF-300:JSON 历史恢复与查找替换 copy 反馈对齐 Electron 的实践指南

导读

本文聚焦 MooTool Compose(Kotlin/Compose Desktop,位于 next-compose/)JSON 工具中两块 UI 状态的跨端对齐工作:一是「历史恢复」后不再写入"已从历史恢复"提示,二是查找条「替换 / 全部替换」成功后显式复位复制反馈 copyState = idle。围绕 next-compose/docs/diff/300-json-history-replace-copy-state.md 展开,结合 Electron JsonTool、Compose JsonScreen、JsonHistoryRestore、EditorBuffer 等源码与测试,说明问题成因、最终行为、底层实现与验证方式,可作为同构 UI 状态对齐的参考案例。

一、背景:Electron 与 Compose 的两处行为落差

Electron 版 JsonTool(next/src/features/json/JsonTool.tsx)定义了工具级 UI 状态机:

type CopyState = 'idle' | 'copied' | 'failed'

其行为基准是:

  • 历史恢复 onApplyHistory:仅执行 update({ content, historyOpen: false })——把历史记录写回编辑器正文并关闭历史对话框,不写 json.notice.restored,也不触碰 copyState。
  • 查找替换 replaceCurrent / replaceAllMatches:替换成功后执行 update({ …, notice: '', copyState: 'idle' })——同时清空状态栏提示、复位复制按钮状态。

Compose 版本(next-compose/composeApp/src/desktopMain/.../features/json/JsonScreen.kt)当时存在两处不一致:

  1. 历史恢复时额外写入了「已从历史恢复」类提示(json.notice.restored),与 Electron 直接改 content 的语义不符;
  2. 「全部替换」通过 setText 批量写入正文,而 EditorBuffer.setText 不触发 onUserDocumentChange,导致复制按钮可能仍停留在「已复制」状态。

DIFF-300 即针对这两处对齐 Electron。

二、目标行为(F04)

本项工作定义的目标行为有两条:

  1. F04:HistoryBrowser 恢复 JSON 正文后,只关闭历史对话框并调用 clearJsonPathQueryResult(),保留既有 notice——与 Electron 直接改 content 的行为一致。
  2. 查找条「替换」「全部替换」成功时,显式置 copyState = idle:
    • 单次替换与 Electron 一致;
    • 全部替换补齐 setText 路径(因为 setText 不会触发用户编辑回调,必须手动复位)。

需要强调:历史恢复不写 json.notice.restored 是刻意为之的跨工具约定,而非省略。next-compose/docs/diff/303-history-restore-no-restored-notice.md 说明:Electron HistoryDialog 与各工具 onApply / onApplyRecord 恢复字段后只关对话框,没有任何「已从历史恢复」类状态栏文案;因此 JSON(DIFF-300)、随手记(DIFF-302)、Host 以及其余声明通用历史的工具统一不写该 notice。

三、历史恢复的实现:从 Electron 到 Compose

3.1 Electron 侧语义

Electron JsonTool.tsx 中,历史恢复的挂载点位于 JsonToolDialogs 的 onApplyHistory:

onApplyHistory={(content) => update({ content, historyOpen: false })}

只做两件事:写入 content、关闭 historyOpen。notice 与 copyState 保持不变。

3.2 Compose 侧实现

Compose 将历史恢复拆成两个正交的部分:

(1)状态回填:JsonHistoryRestore.apply(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/domain/JsonHistoryRestore.kt)

object JsonHistoryRestore {
    fun apply(session: JsonSession, item: HistoryRecord) {
        if (JsonHistoryMetadata.isPathQuery(item.options)) {
            session.pathResult = item.output
            session.dialogTitle = item.summary
            session.dialogBody = item.output
        } else {
            session.pathResult = ""
            session.dialogTitle = ""
            session.dialogBody = ""
        }
    }

    /** JSONPath 历史只恢复结果区,不改编辑器正文。 */
    fun editorText(item: HistoryRecord): String? =
        if (JsonHistoryMetadata.isPathQuery(item.options)) null
        else item.output.ifBlank { item.input }
}

要点:

  • 普通(编辑器)历史:正文写回 output(为空时回退 input),同时清空残留的 JSONPath 结果区;
  • JSONPath 查询历史:只恢复 pathResult / dialogTitle / dialogBody,不碰编辑器正文(editorText 返回 null);
  • 通过 options 中的 marker 区分两种类型,由 JsonHistoryMetadata(JsonHistoryMetadata.kt)负责编码/解码,KIND_EDITOR 与 KIND_PATH_QUERY 两种 kind 编码进 JSON 串。

(2)挂载与写入:JsonScreen 的 HistoryBrowser 恢复回调(JsonScreen.kt#L520-L538)

onRestore = { item ->
    if (!jsonVaultFlushDirtyOrNotice(container, session, monitor) { session.vaultConflict = it }) {
        refresh()
        return@HistoryBrowser
    }
    JsonHistoryRestore.apply(session, item)
    JsonHistoryRestore.editorText(item)?.let { text ->
        onEdt { session.editor.setText(text, recordUndo = true) }
    }
    session.historyOpen = false
    refresh()
}

可见其行为链为:脏 Vault 先 flush(失败则保持历史对话框打开,见 DIFF-357)→ 回填状态 → setText 写正文 → 关历史对话框。整个过程不写 session.notice,因而保留既有提示。注意 JsonHistoryRestore.apply 内部已把 pathResult 清空,这正对应 F04 中的 clearJsonPathQueryResult() 语义——避免历史恢复后残留上一次 JSONPath 查询结果。

3.3 为什么 setText 不会触发表单态更新

EditorBuffer.setText(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/editor/EditorBuffer.kt#L74-L92)通过 suppressUserDocumentChange 计数器压制文档变更回调:

fun setText(value: String, recordUndo: Boolean) {
    suppressUserDocumentChange++
    try {
        if (!recordUndo) { undoManager.discardAllEdits(); area.text = value; undoManager.discardAllEdits() }
        else { atomicDocument { … } }
    } finally { suppressUserDocumentChange-- }
    markChanged()
}

onUserDocumentChange 只在 suppressUserDocumentChange == 0 时触发(EditorBuffer.kt#L360)。测试 EditorBufferUserDocumentChangeTest.kt 直接验证了这一点:

@Test
fun setText_does_not_fire_user_document_change() {
    val buffer = EditorBuffer("")
    var count = 0
    buffer.onUserDocumentChange = { count += 1 }
    buffer.setText("{\"a\":1}", recordUndo = false)
    assertEquals(0, count)
}

因此任何依赖 onUserDocumentChange 重置 copyState 的路径,都必须在 setText 之外显式复位——这正是「全部替换」需要手动补 copyState = idle 的根因。

四、查找替换的 copy 反馈复位

4.1 单次替换

Compose FindBar 的「替换」按钮(JsonScreen.kt#L873-L885):

MooButton(container.t("find.replace"), onClick = {
    onEdt {
        if (!RstaFindNavigation.replaceAndSelectNext(session.editor, session.findQuery, session.replaceText, session.findOptions)) {
            container.toastFindNoMatches()
        } else {
            session.findReplacedCount += 1
            session.clearJsonPathQueryResult()
            session.notice = ""
            session.copyState = CopyFeedbackPolicy.IDLE
        }
        onChanged()
    }
})

单次替换走 RstaFindNavigation.replaceAndSelectNext(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/editor/RstaFindNavigation.kt),其内部通过 editor.setText(next, recordUndo = true) 写回替换结果,然后继续选中下一处或保留本次替换选区。成功后同时:替换计数 +1、清 JSONPath 结果、清 notice、复位 copyState。

4.2 全部替换

「全部替换」(JsonScreen.kt#L886-L898):

MooButton(container.t("find.replaceAll"), onClick = {
    val (next, count) = FindReplace.replaceAll(session.editor.text, session.findQuery, session.replaceText, session.findOptions)
    if (count == 0) {
        container.toastFindNoMatches()
    } else {
        onEdt { session.editor.setText(next, recordUndo = true) }
        session.clearJsonPathQueryResult()
        session.findReplacedCount = count
        session.notice = ""
        session.copyState = CopyFeedbackPolicy.IDLE
    }
    onChanged()
})

匹配引擎在 next-compose/composeApp/src/commonMain/kotlin/com/rememberber/mootool/next/compose/domain/FindReplace.kt 中实现,关键函数:

  • findAll(content, query, options): List<FindMatch>——收集全部匹配区间;
  • replaceAll(content, query, replacement, options): Pair<String, Int>——一次性替换并返回替换次数;
  • replaceCurrent(...)——单次替换,支持选区命中与正则 $1 / $& 替换模板(对齐 Electron applyReplacement)。

查找选项 FindReplaceOptions 提供三个开关:

字段 默认值 含义
matchCase false 大小写敏感
wholeWord false 全词匹配
regex false 正则模式(支持 $1、$& 反向引用)

“全部替换”场景里,正文变更走 setText(不触发 onUserDocumentChange),所以必须在成功后显式执行 session.copyState = CopyFeedbackPolicy.IDLE,否则工具栏复制按钮会停留在「已复制」文案——这正是 DIFF-300 补齐的路径。count == 0 时仅弹 info toast(toastFindNoMatches),不触碰 notice / copyState,与 Electron 一致。

五、copy 反馈状态机的底层支撑

5.1 CopyFeedbackPolicy

next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/ui/workbench/CopyFeedbackPolicy.kt 定义了统一的复制反馈状态机:

object CopyFeedbackPolicy {
    const val IDLE = "idle"
    const val COPIED = "copied"
    const val FAILED = "failed"
    const val RESET_MS = 1400L

    fun afterCopy(success: Boolean): String = if (success) COPIED else FAILED

    fun buttonKey(state: String, idleKey: String = "json.action.copy"): String = when (state) {
        COPIED -> "json.action.copied"
        FAILED -> "json.notice.copyFailed"
        else -> idleKey
    }
}
  • 三态:idle / copied / failed;
  • RESET_MS = 1400:复制反馈展示约 1.4 秒后自动回到 idle;
  • buttonKey 把状态映射为 i18n key(json.action.copied、json.notice.copyFailed 等)。

JsonSession(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/sessions/SessionManager.kt#L114-L157)持有 var copyState: String = "idle" 与 var copyGeneration: Int = 0。JsonScreen 的工具栏通过 LaunchedEffect(session.copyGeneration, session.copyState) 在 RESET_MS 后把状态复位回 IDLE。

5.2 复制按钮文案联动

工具栏复制按钮(JsonScreen.kt#L714-L720):

MooButton(container.t(CopyFeedbackPolicy.buttonKey(session.copyState)), onClick = {
    val outcome = copyText(session.editor.text, container)
    session.notice = outcome.notice
    session.copyState = CopyFeedbackPolicy.afterCopy(outcome.success)
    session.copyGeneration += 1
    onChanged()
})

底层剪贴板写入在 AppContainer.copyText(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/app/AppContainer.kt#L264-L273):通过 AWT Toolkit.getDefaultToolkit().systemClipboard.setContents 写入,成功/失败分别弹 json.notice.copied / json.notice.copyFailed toast。

结果弹层的「复制」(JsonScreen.kt#L1861-L1867)走同一套 afterCopy + copyGeneration,即 DIFF-296 对齐的“结果弹层复制同步工具栏反馈”——说明 copyState 是跨 UI 入口共享的全局状态,任何入口的复制动作都会反映到工具栏按钮上;因此替换操作后如果不复位,用户会看到按钮错误地显示「已复制」。

5.3 复制反馈的整体流程

复制按钮 / 结果弹层「复制」
   → AppContainer.copyText() 写 AWT 剪贴板
   → CopyFeedbackPolicy.afterCopy(success)  → copied / failed
   → session.copyState / copyGeneration 更新
   → LaunchedEffect 延迟 1400ms 复位 idle
   → 工具栏按钮文案按 buttonKey() 切换

与之并列的“复位触发点”包括:编辑器用户手动编辑(onUserDocumentChange,见 JsonScreen.kt#L215-L221)、单次替换、全部替换、以及正文整体被 setText 覆盖的各类导入/转换/历史恢复路径。

六、测试验证

JsonHistoryRestoreTest(next-compose/composeApp/src/desktopTest/kotlin/com/rememberber/mootool/next/compose/domain/JsonHistoryRestoreTest.kt)覆盖历史恢复的两条分支:

  1. 编辑器历史恢复正文且不残留 JSONPath 结果:构造 options = JsonHistoryMetadata.encodeEditor() 的记录,apply 后 editorText 返回格式化输出,session.pathResult 被清空;
  2. JSONPath 历史只恢复结果区:options = JsonHistoryMetadata.encodePathQuery() 时,editorText 返回 null,pathResult 与 dialogTitle 正确回填。

RstaFindNavigationTest(next-compose/composeApp/src/desktopTest/kotlin/com/rememberber/mootool/next/compose/editor/RstaFindNavigationTest.kt)验证单次替换后选区推进到下一处匹配;FindReplaceTest(next-compose/composeApp/src/commonTest/kotlin/com/rememberber/mootool/next/compose/domain/FindReplaceTest.kt)验证 replaceAllIsOneTransactionCount 等替换计数语义。

本项工作声明的验证命令为:

./gradlew :composeApp:desktopTest --offline

并对照 next/src/features/json/JsonTool.tsx 的 onApplyHistory / replaceCurrent 进行手工核验(该文件即 Electron 侧基准实现,见 JsonTool.tsx 与 JsonTool.tsx)。

七、参考文档脉络

DIFF-300 是 JSON 工具状态对齐系列中的一环,仓库中可直接延伸阅读的相关文档(均在 next-compose/docs/diff/):

八、小结

DIFF-300 的实质是「以 Electron 行为为基准,收敛 Compose 的 UI 状态副作用」:历史恢复只写正文并关对话框(不写 restored notice、不写 JSONPath 残留结果),查找替换成功后显式复位 copyState = idle。其中最具借鉴意义的是对 EditorBuffer.setText 不触发 onUserDocumentChange 这一底层特性的识别——它提醒我们:凡是经批量写入(setText/replaceAllText)改变正文的操作,都需要自行收敛依赖用户编辑回调的派生状态。

登录后查看全文
MooTool