MooTool Compose 版 Host 查找条「已替换」计数与会话快照持久化实现解析(DIFF-288)
MooTool Compose 版 Host 查找条「已替换」计数与会话快照持久化实现解析(DIFF-288)
导读
本文围绕 MooTool Next Compose 桌面版 Host 工具的 DIFF-288 变更展开:在 Host 查找/替换条中引入「已替换」计数(findReplacedCount),并将 JSON、随手记、Host、HTTP 四个工具的命中数文案统一为「共找到: N」,最终与 Electron 版 HostTool/FindReplaceBar 行为对齐。读完本文,你将掌握该计数的会话生命周期(快照/恢复往返)、查找条的归零与自增规则、相关 i18n 文案键,以及底层的 FindReplace 替换引擎实现,并能据此复现与验证全部行为。
背景:Electron 与 Compose 的查找条行为差异
MooTool 同时维护 Electron 与 Compose Desktop 两套实现。在 Electron 侧,HostTool 与 FindReplaceBar 早已具备两个关键能力:
replacedCount:记录本次查找会话中已完成替换的次数;findReplace.foundPrefix(「共找到:」):命中数文案前缀。
而 Compose 版 Host 此前只有替换能力,没有任何计数;同时 JSON/随手记/HTTP/Host 四个工具的命中数文案写的是 {count} 处匹配,与 Electron 的「共找到: N」不一致,json.find.matches 这条 i18n 文案在语义上被误用在了所有工具的查找条上。DIFF-288 正是为解决这两个一致性缺口而设计,前序 DIFF-287 已为 JSON/随手记补齐「已替换」计数,DIFF-288 则将其延伸到 Host 并完成文案统一。
核心设计:findReplacedCount 随会话快照往返
会话状态与会话快照
Compose 端每个工具都有自己的 Session 与可序列化的 SessionSnapshot。Host 的会话定义位于 SessionManager.kt:
@Serializable
data class HostSessionSnapshot(
val selectedId: String = "",
val name: String = "",
val content: String = "",
val query: String = "",
val includeContent: Boolean = true,
val findOpen: Boolean = false,
val findQuery: String = "",
val replaceText: String = "",
val matchCase: Boolean = false,
val wholeWord: Boolean = false,
val regex: Boolean = false,
val findReplacedCount: Int = 0,
)
运行时会话 HostSession 中对应字段为 var findReplacedCount: Int = 0。DIFF-288 的关键约束是:该计数必须能随会话往返(round-trip)——即从 snapshotState() 保存、经序列化落盘、再从 restore() 恢复时数值不丢失:
fun snapshotState(): HostSessionSnapshot = HostSessionSnapshot(
// ...
findReplacedCount = findReplacedCount,
)
fun restore(snapshot: HostSessionSnapshot) {
// ...
findReplacedCount = snapshot.findReplacedCount
notice = ""
error = ""
// 其余一次性会话状态(applying、systemOpen 等)重置
}
注意 restore() 恢复 findReplacedCount 的同时会把 notice、error、applying 等一次性运行时状态清空,说明该计数被当作需要跨会话保留的 UI 状态对待,而非仅存活于单次交互。
测试验证:快照往返
对应测试位于 HostSessionSnapshotTest.kt:
@Test
fun snapshot_roundTrips_findReplacedCount() {
val session = HostSession()
session.findReplacedCount = 5
val restored = HostSession().also { it.restore(session.snapshotState()) }
assertEquals(5, restored.findReplacedCount)
}
这一测试直接印证了「findReplacedCount 随 snapshotState/restore 往返」的行为约定。同理,JSON/随手记在 DIFF-287 中也通过 JsonSessionSnapshot/QuickNoteSessionSnapshot 的 findReplacedCount 字段与 JsonSessionSnapshotTest/QuickNoteSessionSnapshotTest 完成同样的往返验证。
Host 查找条行为细则:归零、自增与展示
Host 查找条 UI 位于 HostScreen.kt。DIFF-288 规定了三个方向的行为:
1. 打开 / 关闭 / 改查找词 / 改选项时归零
| 触发时机 | 代码位置 | 行为 |
|---|---|---|
打开查找(openHostFindReplace) |
HostScreen.kt L174-L179 |
session.findReplacedCount = 0 |
关闭查找(closeHostFindReplace / 查找条 closeFind) |
HostScreen.kt L181-L185、L902-L906 |
session.findReplacedCount = 0 |
修改查找词 findQuery |
L920-L926 | 输入回调中归零 |
| 切换 matchCase / wholeWord / regex 选项 | L941-L955 | 三个开关回调中均归零 |
语义上「已替换计数」只对当前查找词与当前选项组合有意义,一旦条件变化,旧的计数立刻失效,因此全部硬性归零。查找条内修改替换文本(replaceText)则不归零——它只影响将来替换动作的结果,不改变“已替换”这一既有事实。
2. 单次替换 +1、全部替换设为 count
单次「替换」按钮逻辑(L973-L1002):
val (next, match) = FindReplace.replaceCurrent(
session.content, session.findQuery, session.replaceText,
session.findOptions, caret, selection.start, selection.end,
)
if (match == null) {
container.toastFindNoMatches()
} else {
session.content = next
session.findReplacedCount += 1 // 单次替换成功 +1
session.notice = "" // DIFF-306:清空状态栏提示
onContentFieldChange(
HostFindNavigation.afterReplaceAndSelectNext(
next, session.findQuery, session.findOptions, contentField, match
)
)
}
「全部替换」按钮逻辑(L1003-L1014):
val (next, count) = FindReplace.replaceAll(
session.content, session.findQuery, session.replaceText, session.findOptions
)
if (count == 0) {
container.toastFindNoMatches()
} else {
session.content = next
onContentFieldChange(contentField.copy(text = next))
session.findReplacedCount = count // 全部替换直接设为替换次数
session.notice = "" // DIFF-301:不写 matches 状态栏文案
}
其中 toastFindNoMatches() 使用的是 DIFF-307 引入的 find.noMatches(中文「未找到匹配内容」/ 英文 “No matches found”),与 Electron findReplace.noMatches 对齐。
3. 查找条展示「共找到: N」与「已替换: N」
查找条右侧两个文本节点分别展示命中数与替换计数(L956-L960、L1015-L1019):
Text("${container.t("find.foundPrefix")} ${matches.size}", ...) // 共找到: N
Text("${container.t("find.replacedPrefix")} ${session.findReplacedCount}", ...) // 已替换: N
matches 由 FindReplace.findAll(session.content, session.findQuery, session.findOptions)(L889)实时计算得出。两条 i18n 文案键位于 Translator.kt:
| 键 | 中文 | 英文 | 日文 |
|---|---|---|---|
find.foundPrefix |
共找到: | Found: | — |
find.replacedPrefix |
已替换: | Replaced: | — |
json.find.matches |
{count} 处匹配 | {count} matches | — |
json.notice.noMatches |
未找到匹配内容 | No matches found | — |
find.noMatches |
未找到匹配内容 | No matches found | 一致する内容がありません |
DIFF-288 的核心目标之一,正是让查找条命中数统一走 find.foundPrefix,从而彻底弃用 json.find.matches 在查找条场景的误用。
文案统一:JSON/随手记/Host/HTTP 命中数对齐
DIFF-288 明确要求 JSON、随手记、Host、HTTP 四个工具的查找条命中数一律改为 find.foundPrefix + 数字。从源码看该改动已全部落地:
- Host:
HostScreen.ktL957${container.t("find.foundPrefix")} ${matches.size}; - JSON:
JsonScreen.ktL859 同款写法,替换计数展示在 L900; - 随手记:
QuickNoteScreen.ktL1862 / L1905 同款写法; - HTTP:
HttpScreen.ktL1254${container.t("find.foundPrefix")} ${matches.size}。
四个工具使用完全相同的文案键组合,保证跨工具、跨平台(Electron ↔ Compose)的文案一致性。同时,与「已替换」计数配套的 findReplacedCount 归零/自增逻辑也已同步到 JSON(JsonScreen.kt L311-L323、L808-L900)与随手记(QuickNoteScreen.kt L240-L340、L1795-L1905)。
状态栏衔接:替换成功不写 matches 文案
DIFF-288 引用了两份上下游规范,约束替换成功后的状态栏行为:
- DIFF-301(全部替换):Host/随手记「全部替换」成功时只更新正文与
findReplacedCount = count,session.notice = "",不再写json.find.matches;无匹配时仍用find.noMatches提示。其参照实现是 ElectronHostTool.replaceCurrent(true)/QuickNoteTool.replaceCurrent(true)——成功时仅更新正文与replacedCount,无状态栏 notice。 - DIFF-306(单次替换):Host 单次「替换」成功时同样
session.notice = ""(与全部替换、与 JSON 查找条替换分支一致),避免残留「已保存/已导出」等旧提示。
这两条规则共同形成「替换动作成功后状态栏不显示任何 matches 文案,只由查找条内的 已替换: N 计数呈现结果」的统一行为。Electron 侧参照实现位于 HostTool.tsx:replaceCurrent(false) 成功时 setReplacedCount((count) => count + 1),replaceCurrent(true) 成功时 setReplacedCount(result.count);无匹配时 actions.toast.info(t('findReplace.noMatches'))。
底层原理:FindReplace 引擎与替换后导航
替换引擎
所有计数都建立在 FindReplace.kt(commonMain,跨平台共享)之上:
findAll(content, query, options):返回全部FindMatch(start, end),空串匹配会被跳过以避免死循环(L15-L31);replaceCurrent(content, query, replacement, options, fromIndex, selectionStart, selectionEnd):优先替换当前选中且与查找词完全相等的选区,否则从fromIndex向后找下一处匹配替换;返回Pair<String, FindMatch?>(L49-L75);replaceAll(content, query, replacement, options):一次性替换全部命中,返回Pair<String, Int>,第二个返回值就是「全部替换」所需的count(L77-L97)。
replaceAll 的返回值设计(替换后全文 + 命中数)直接支撑了 session.findReplacedCount = count 这一行赋值;replaceCurrent 的 FindMatch? 返回值则支撑了单次替换后的 +1 判断。
替换后选中下一处
单次替换后,Host 通过 HostFindNavigation.kt 的 afterReplaceAndSelectNext 从本次替换区间末尾继续向后查找并选中下一处匹配:
fun afterReplaceAndSelectNext(
content: String, query: String, options: FindReplaceOptions,
field: TextFieldValue, replaced: FindMatch?,
): TextFieldValue {
val withReplacement = afterReplace(content, field, replaced)
if (replaced == null) return withReplacement
val next = FindReplace.findNext(content, query, options, replaced.end, forward = true) ?: return withReplacement
return withReplacement.copy(selection = TextRange(next.start, next.end))
}
这对应 DIFF-278 与 Electron replaceCurrent 成功后 findNextMatch(..., result.nextFrom, true) 选中下一处的行为,使「逐处替换」流程可以连续回车操作。该逻辑由 HostFindNavigationTest 覆盖(见 HostFindNavigationTest.kt)。
验证方法
DIFF-288 的验证手段非常轻量,仅依赖现有测试体系:
./gradlew :composeApp:desktopTest --offline
其中核心用例为 HostSessionSnapshotTest(验证 findReplacedCount 的快照往返)。相关功能的完整回归面还包括:
JsonSessionSnapshotTest/QuickNoteSessionSnapshotTest:验证 JSON/随手记的findReplacedCount往返(DIFF-287);HostFindNavigationTest:覆盖跳转与替换后选中下一处(DIFF-277/278);TextFieldFindSeedTest:覆盖打开查找预填选区(DIFF-276);FindHighlightTransformationTest:覆盖查找高亮(DIFF-279)。
由于 findReplacedCount 是纯内存会话状态、通过 @Serializable 快照往返,整个功能可以在不引入额外依赖的前提下被桌面测试完整覆盖。
总结
DIFF-288 以「已替换计数 + 命中文案统一」为切入点,完成了 Compose Host 查找条与 Electron 的行为对齐:
- 会话持久化:
findReplacedCount写入HostSessionSnapshot,随snapshotState()/restore()往返,并有HostSessionSnapshotTest直接背书; - 查找条行为:打开/关闭/改查找词/改选项归零,单次替换
+1,全部替换设为count,查找条内实时展示共找到: N与已替换: N; - 文案统一:JSON/随手记/Host/HTTP 四工具命中数统一为
find.foundPrefix前缀,弃用json.find.matches在查找条中的误用; - 状态栏规范:配合 DIFF-301/306,单次与全部替换成功后
notice一律清空,结果只由查找条计数呈现。
若需要继续了解该功能的相邻实现,可顺延阅读 DIFF-287(JSON/随手记已替换计数)、DIFF-301(全部替换不写 matches)、DIFF-306(单次替换清空 notice) 与 DIFF-307(find.noMatches 文案)。