MooTool DIFF-300:JSON 历史恢复与查找替换 copy 反馈对齐 Electron 的实践指南
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)当时存在两处不一致:
- 历史恢复时额外写入了「已从历史恢复」类提示(
json.notice.restored),与 Electron 直接改content的语义不符; - 「全部替换」通过
setText批量写入正文,而EditorBuffer.setText不触发onUserDocumentChange,导致复制按钮可能仍停留在「已复制」状态。
DIFF-300 即针对这两处对齐 Electron。
二、目标行为(F04)
本项工作定义的目标行为有两条:
- F04:
HistoryBrowser恢复 JSON 正文后,只关闭历史对话框并调用clearJsonPathQueryResult(),保留既有notice——与 Electron 直接改content的行为一致。 - 查找条「替换」「全部替换」成功时,显式置
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/$&替换模板(对齐 ElectronapplyReplacement)。
查找选项 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)覆盖历史恢复的两条分支:
- 编辑器历史恢复正文且不残留 JSONPath 结果:构造
options = JsonHistoryMetadata.encodeEditor()的记录,apply后editorText返回格式化输出,session.pathResult被清空; - 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/):
- 294-json-transform-history-summary.md:格式化/压缩等 transform 的历史摘要对齐 Electron
runTransform; - 296-json-result-dialog-copy-feedback.md:结果弹层复制同步工具栏 copy 反馈(引入
copyGeneration); - 302-quicknote-history-restore-notice.md:随手记历史恢复同样不写 restored notice;
- 303-history-restore-no-restored-notice.md:通用历史统一不写
json.notice.restored; - 357-history-restore-flush-vault.md:历史恢复前先 flush 脏 Vault 片段。
八、小结
DIFF-300 的实质是「以 Electron 行为为基准,收敛 Compose 的 UI 状态副作用」:历史恢复只写正文并关对话框(不写 restored notice、不写 JSONPath 残留结果),查找替换成功后显式复位 copyState = idle。其中最具借鉴意义的是对 EditorBuffer.setText 不触发 onUserDocumentChange 这一底层特性的识别——它提醒我们:凡是经批量写入(setText/replaceAllText)改变正文的操作,都需要自行收敛依赖用户编辑回调的派生状态。