MooTool Compose 版 Host 查找条「已替换」计数与会话快照持久化实现解析(DIFF-288)

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

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.kt L957 ${container.t("find.foundPrefix")} ${matches.size};
  • JSON:JsonScreen.kt L859 同款写法,替换计数展示在 L900;
  • 随手记:QuickNoteScreen.kt L1862 / L1905 同款写法;
  • HTTP:HttpScreen.kt L1254 ${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 提示。其参照实现是 Electron HostTool.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 的行为对齐:

  1. 会话持久化:findReplacedCount 写入 HostSessionSnapshot,随 snapshotState()/restore() 往返,并有 HostSessionSnapshotTest 直接背书;
  2. 查找条行为:打开/关闭/改查找词/改选项归零,单次替换 +1,全部替换设为 count,查找条内实时展示 共找到: N 与 已替换: N;
  3. 文案统一:JSON/随手记/Host/HTTP 四工具命中数统一为 find.foundPrefix 前缀,弃用 json.find.matches 在查找条中的误用;
  4. 状态栏规范:配合 DIFF-301/306,单次与全部替换成功后 notice 一律清空,结果只由查找条计数呈现。

若需要继续了解该功能的相邻实现,可顺延阅读 DIFF-287(JSON/随手记已替换计数)、DIFF-301(全部替换不写 matches)、DIFF-306(单次替换清空 notice) 与 DIFF-307(find.noMatches 文案)。

登录后查看全文
MooTool