MooTool Next Compose 查找条「已替换」计数实现解析:会话持久化、归零时机与单次/全部替换语义

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

MooTool Next Compose 查找条「已替换」计数实现解析:会话持久化、归零时机与单次/全部替换语义

导读

在 MooTool Next Compose(Compose Multiplatform Desktop 独立产品线)中,JSON 格式化与随手记(QuickNote)两个编辑型工具内置了查找替换条(FindBar)。本篇文章以设计文档 DIFF-287:JSON/随手记查找条「已替换」计数 为骨架,结合 next-compose/ 下会话层、界面层与测试源码,完整讲解 findReplacedCount 从「Electron 已具备」到「Compose 补齐」的差距背景、四条行为契约、SQLite 快照持久化、界面展示与国际化文案,以及单次替换 +1、全部替换设为总替换次数的底层实现路径。读完本文,你可以复现验证命令、理解同类查找条(Host)的扩展方式,并掌握「查找状态归零」这类交互状态机的标准实现手法。

一、问题背景:Electron 有计数,Compose 此前没有

在 Electron 版中,FindReplaceBar 组件把「已替换计数」作为一等属性暴露给所有使用方:

// next/src/shared/components/FindReplaceBar.tsx
export type FindReplaceBarProps = {
  findText: string
  replaceText: string
  matchCount: number
  replacedCount: number          // ← 已替换计数
  ...
}

渲染层通过 findReplace.replacedPrefix 文案拼接计数:

<span className="find-replace-bar__count">{t('findReplace.replacedPrefix')} {replacedCount}</span>

而 DIFF-287 明确指出现状差距:

Electron FindReplaceBar 展示 replacedCount(findReplace.replacedPrefix)。Compose JSON/随手记查找条此前无对应计数与会话持久化。

也就是说,Compose 版本此前虽然具备查找、上下跳转、单次替换、全部替换能力,但缺少两个东西:一是界面上没有「已替换: N」的实时反馈;二是这个计数没有进入 JsonSession / QuickNoteSession 的快照,导致工具切换或应用重启后无法恢复。DIFF-287 就是补齐这两点的实现记录。

二、行为契约:四条规则定义一个替换计数状态机

设计文档将行为收敛为四条可验证的规则:

规则 行为
R1 快照持久化 JsonSession / QuickNoteSession 的 findReplacedCount 写入快照(snapshot),并随 restore 恢复
R2 界面展示 查找条展示 find.replacedPrefix + 计数,即「已替换: N」
R3 归零时机 打开查找条、修改查找词、修改查找选项(大小写/全词/正则)、关闭查找条时,计数归零
R4 计数语义 单次替换成功 +1;全部替换成功时,计数直接设为替换次数

这四条规则同时出现在后续的 DIFF-288:Host 查找条已替换计数 中,说明它是整个 Compose 查找替换体系的公共约定:凡是带替换能力的查找条,都必须满足 R2~R4,且计数随会话快照往返。

三、会话层:findReplacedCount 进入快照并支持 round-trip

3.1 三个会话的字段定义

next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/sessions/SessionManager.kt 是全部工具会话(Session)的集中地。三个与替换计数相关的会话都同时定义了「可序列化快照」与「运行时会话」两个版本:

  • JsonSessionSnapshot / JsonSession(SessionManager.kt L89 / L114):
    // 快照侧(默认值保证旧快照可反序列化)
    val findReplacedCount: Int = 0,
    // 运行时侧
    var findReplacedCount: Int = 0
    
  • QuickNoteSessionSnapshot / QuickNoteSession(L1689 / L1717):
    val findReplacedCount: Int = 0,   // 快照
    var findReplacedCount: Int = 0    // 运行时
    
  • HostSessionSnapshot / HostSession(L1350 附近 / L1364),由 DIFF-288 补充,实现完全一致的字段模式。

3.2 snapshot / restore 的往返

以 JsonSession 为例,snapshot()(L180-L206)把 findReplacedCount 写入 JsonSessionSnapshot;restore()(L208-L232)再从快照读回:

fun snapshot(): JsonSessionSnapshot = JsonSessionSnapshot(
    ...
    findReplacedCount = findReplacedCount,   // 写入快照
    ...
)

fun restore(snapshot: JsonSessionSnapshot) {
    ...
    findReplacedCount = snapshot.findReplacedCount   // 恢复会话
    ...
}

值得注意的是,快照中查找条的其余状态(findOpen、findQuery、replaceText、matchCase、wholeWord、regex)也一并持久化,findReplacedCount 是与它们并列的「查找条会话状态」之一。这说明 Compose 的会话快照不是零散字段,而是把整个查找条 UI 状态作为一个整体持久化。

3.3 持久化介质:SQLite 的 tool_sessions 表

SessionManager 通过 SessionStore 读写快照。真正的落盘实现位于 next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/storage/Database.kt(L394-L418):

class SessionStore(private val database: AppDatabase) {
    fun load(toolId: String): String? {
        // SELECT state_json FROM tool_sessions WHERE tool_id = ?
    }
    fun save(toolId: String, stateJson: String) {
        // INSERT INTO tool_sessions(tool_id, schema_version, state_json, updated_at)
        // ... ON CONFLICT(tool_id) DO UPDATE SET ...
    }
}

即每个工具一行记录,state_json 存放 @Serializable 快照的 JSON 序列化结果,schema_version 当前为 1。反序列化使用:

private val jsonCodec = Json { ignoreUnknownKeys = true }

ignoreUnknownKeys = true 保证:当快照 JSON 中新增字段(如本次新增的 findReplacedCount)而旧版本程序读取时不会崩溃;反之,本次加载旧版快照时,缺省的 findReplacedCount 会落到默认值 0。这是「会话状态向后兼容」的关键设计,也是 DIFF-287 敢于给快照加字段的前提。

四、界面层:查找条的展示与归零实现(JSON 为参照)

JsonScreen.kt 中的 FindBar 组合函数(next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/features/json/JsonScreen.kt L799-L906)完整实现了 R2、R3、R4。

4.1 命中数与已替换计数并列展示

查找条在「全部替换」按钮之后渲染第二个计数文本:

// 命中数(只读):“共找到: N”
Text(
    "${container.t("find.foundPrefix")} ${matches.size}",
    color = MooTheme.colors.textSecondary,
    fontSize = 12.sp,
)
// 已替换计数:“已替换: N”
Text(
    "${container.t("find.replacedPrefix")} ${session.findReplacedCount}",
    color = MooTheme.colors.textSecondary,
    fontSize = 12.sp,
)

其中 matches 来自 FindReplace.findAll(session.editor.text, session.findQuery, session.findOptions),实时统计当前查询命中数;session.findReplacedCount 是会话中累计的替换数。两者语义不同:命中数是「当前查找词还能找到多少处」,已替换数是「本次查找会话已经替换成功了几处」,正是 DIFF-287 新增的反馈维度。

4.2 归零时机的全部落点

对照 R3,JsonScreen.kt 中每一处把 findReplacedCount 置零的代码点如下:

归零场景 代码位置 说明
快捷键打开查找条 L311 openFindBarSeedingSelection 回调中 findOpen = true 的同时归零
编辑器内 Ctrl/Cmd+F 打开 L419 onFind 回调,同样在打开时归零
Esc 关闭查找条 L323 关闭时归零
点击「关闭」按钮 L808 closeFind() 内归零
修改查找词 L828 查找词输入框 onChange 归零
切换 matchCase 选项 L845 选项翻转后归零
切换 wholeWord 选项 L850 同上
切换 regex 选项 L855 同上

从源码结构看,归零逻辑并没有收敛到一个函数,而是散落在各个交互回调里——这是有意为之的「就地更新」写法:所有会改变匹配结果的交互(改词、改选项、重新打开)都让计数失效并归零,避免出现「已替换计数与新查询无关」的误导性 UI 状态。

4.3 单次替换 +1:替换成功才计数

「替换」按钮的回调(L873-L885)是 R4 的第一半:

MooButton(container.t("find.replace"), onClick = {
    onEdt {
        if (!RstaFindNavigation.replaceAndSelectNext(session.editor, session.findQuery, session.replaceText, session.findOptions)) {
            container.toastFindNoMatches()          // 无匹配:只 toast,不计数
        } else {
            session.findReplacedCount += 1          // 替换成功才 +1
            session.clearJsonPathQueryResult()
            session.notice = ""
            session.copyState = CopyFeedbackPolicy.IDLE
        }
        onChanged()
    }
})

两个细节值得注意:

  1. 成功才计数:replaceAndSelectNext 返回 false 表示无匹配可替换,此时走 toastFindNoMatches() 分支,计数不变;只有真正执行了一次替换并选中下一处,才执行 findReplacedCount += 1。
  2. 配套状态清理:替换成功后同步清空 JSONPath 查询结果(clearJsonPathQueryResult())、状态栏 notice 与复制反馈 copyState。这与 Electron 版 replaceCurrent 的行为对齐,也是后续 DIFF-306:Host 单次替换成功清空状态栏 notice 的参照来源。

4.4 全部替换:计数直接等于替换次数

「全部替换」按钮(L886-L898)使用 FindReplace.replaceAll 一次性完成替换并拿到总次数:

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()          // 0 处:仅提示,不写编辑器
    } else {
        onEdt { session.editor.setText(next, recordUndo = true) }  // 单次事务写入,可撤销
        session.clearJsonPathQueryResult()
        session.findReplacedCount = count        // 计数直接等于替换次数
        session.notice = ""
        session.copyState = CopyFeedbackPolicy.IDLE
    }
    onChanged()
})

这里实现了 R4 的第二半:findReplacedCount = count 而不是 += count。原因在于每次打开查找条 / 改词 / 改选项都会先归零(R3),因此在一次查找会话内,全部替换后计数必然等于本次替换次数,直接赋值语义最干净。同时 count == 0 分支不会修改编辑器文本、也不会改变计数,仅弹出无匹配提示——这与 DIFF-283:JSON 查找无匹配提示 定义的「无匹配时 toast、不写状态栏」一致。

五、底层支撑:FindReplace 引擎的返回结构与选项语义

计数之所以能精确表达为「单次替换次数」和「全部替换次数」,依赖的是 next-compose/composeApp/src/commonMain/kotlin/com/rememberber/mootool/next/compose/domain/FindReplace.kt 的返回设计。

FindReplace 是一个纯 Kotlin 对象,三个核心函数的签名:

fun findAll(content: String, query: String, options: FindReplaceOptions): List<FindMatch>
fun replaceCurrent(content: String, query: String, replacement: String, options: FindReplaceOptions,
                   fromIndex: Int, selectionStart: Int = -1, selectionEnd: Int = -1): Pair<String, FindMatch?>
fun replaceAll(content: String, query: String, replacement: String, options: FindReplaceOptions): Pair<String, Int>
  • replaceAll 返回 Pair<String, Int>,第二个元素就是本次替换的次数,正好被 FindBar 的 val (next, count) = ... 解构使用。
  • 替换选项 FindReplaceOptions(matchCase, wholeWord, regex) 与快照中持久化的三个布尔字段一一对应,构建正则时:
    val source = if (options.regex) query else Regex.escape(query)
    val wrapped = if (options.wholeWord) "\\b(?:$source)\\b" else source
    // matchCase = false 时追加 RegexOption.IGNORE_CASE
    
  • 正则模式支持 $1 / $& 捕获组替换,\n / \r / \t / \\ 转义(expandReplacement,与 Electron applyReplacement 对齐)。

在 next-compose/composeApp/src/commonTest/kotlin/com/rememberber/mootool/next/compose/domain/FindReplaceTest.kt 中,replaceAllIsOneTransactionCount() 直接验证了「一次事务 + 正确次数」的核心语义:

val (next, count) = FindReplace.replaceAll("a-a-a", "a", "b", FindReplaceOptions())
assertEquals("b-b-b", next)
assertEquals(3, count)

这个测试从引擎层保证了:FindReplaceBar 展示的「已替换: 3」与实际文本被替换的次数严格一致,不存在 UI 计数与引擎返回次数不一致的路径。

六、随手记(QuickNote):同一套模式的复刻

next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/features/quicknote/QuickNoteScreen.kt 的 QuickNoteFindBar(L1782-L1909)完整复刻了上述模式,但针对 Markdown 文档编辑做了细微差别:

  • 命中数展示:"${container.t("find.foundPrefix")} ${matches.size}"(L1862)
  • 已替换展示:"${container.t("find.replacedPrefix")} ${session.findReplacedCount}"(L1905)
  • 归零落点:关闭 L1795、改词 L1826、三个选项开关 L1848/L1853/L1858
  • 单次替换:session.findReplacedCount += 1(L1881)
  • 全部替换:session.findReplacedCount = count(L1896)

与 JSON 版本唯一的差异在「替换成功后写 notice」:QuickNote 会调用 quickNoteNoticeOnUserDocumentChange(...) 提示列编辑等上下文信息(L1882、L1897),而 JSON 版在 DIFF-283 与相关后续 DIFF 中统一写空 notice。但替换计数本身的语义(成功 +1 / 全部 = count)完全一致。

七、国际化:find.replacedPrefix 与 find.foundPrefix 文案

计数文案不是硬编码字符串,而是走统一的翻译键。Compose 侧定义在 next-compose/composeApp/src/desktopMain/kotlin/com/rememberber/mootool/next/compose/i18n/Translator.kt:

key 简体中文 英文 日文
find.replacedPrefix 已替换: Replaced: 置換済み:
find.foundPrefix 共找到: Found: 合計:
find.replace / find.replaceAll 替换 / 全部替换 Replace / Replace all —

Electron 侧的同一组键在 next/src/shared/i18n/messages.ts(L181-L182 等)中定义,值同为「已替换:」「共找到:」,保证两条产品线的界面文案一一对应。日文 置換済み: 说明该计数文案同时覆盖 Compose 的完整三语文案体系。

八、测试验证:round-trip 与运行命令

DIFF-287 的验证手段是快照往返(round-trip)单元测试,两个测试文件都位于 next-compose/composeApp/src/desktopTest/kotlin/com/rememberber/mootool/next/compose/sessions/ 下:

JsonSessionSnapshotTest.kt(L14-L18):

session.findReplacedCount = 7
val restored = JsonSession().also { it.restore(session.snapshot()) }
assertEquals(7, restored.findReplacedCount)

QuickNoteSessionSnapshotTest.kt(snapshot_roundTrips_findReplacedCount):

val session = QuickNoteSession()
session.findReplacedCount = 3
val restored = QuickNoteSession().also { it.restore(session.snapshot()) }
assertEquals(3, restored.findReplacedCount)

两个测试都采用「先 snapshot() 再 restore()」的完整往返方式,覆盖了新增字段在序列化→SQLite JSON→反序列化链路中的完整性。随后的 HostSessionSnapshotTest.kt 也加入了对 findReplacedCount = 5 的往返断言(DIFF-288)。

运行验证命令(在 next-compose/ 目录下):

./gradlew :composeApp:desktopTest --offline

--offline 表示纯本地依赖解析,不需要访问远程仓库。整个 desktopTest 任务同时运行桌面端与 common 端测试(含 FindReplaceTest 的引擎断言),是 Compose 产品线统一的单元验证入口。

九、扩展到 Host:一个 DIFF 序列的完整链路

DIFF-287 不是孤立的。围绕「替换计数」,next-compose/docs/diff/ 目录下形成一个完整的功能补齐序列,可作为同类功能的演进范式:

文档 内容
DIFF-287 JSON/随手记查找条「已替换」计数 + 会话持久化
DIFF-288 Host 查找条已替换计数;同时把 JSON/随手记/Host/HTTP 的命中数文案统一改为 find.foundPrefix(「共找到:」)
DIFF-301 Host/随手记「全部替换」成功不写 matches 状态栏,notice = ""
DIFF-306 Host 单次替换成功同样清空 notice,与 JSON 查找条对齐

例如 HostScreen.kt 的 FindBar(L882-L1019)在 DIFF-288 后与 JSON 版保持完全一致的四条规则:展示 find.replacedPrefix(L1016)、改词/选项/关闭归零(L904、L924、L943、L948、L953)、单次替换 +1(L989)、全部替换 = count(L1010),并且在替换成功时清空 session.notice = ""(L990、L1011)。

值得注意的是 HTTP 响应查找条是一个只读查找条:HttpScreen.kt 的 HttpFindBar 只展示 find.foundPrefix(L1254),没有 findReplacedCount 与替换按钮,因为 HTTP 响应正文不允许就地编辑替换。这与 EditorFindOnlyBar.kt(只读查找条)的定位一致——「已替换」计数只属于具备替换能力的编辑器型工具(JSON、随手记、Host)。

十、小结:替换计数的设计取舍

从 DIFF-287 及其配套源码可以总结出这套「已替换计数」的实现要点:

  1. 计数归属会话而非组件:findReplacedCount 放在 JsonSession / QuickNoteSession / HostSession 上,随快照持久化到 SQLite,工具切换、应用重启后计数与查找词/选项一并恢复;
  2. 归零是交互契约:凡是「匹配结果可能变化」的交互(打开、改词、改选项、关闭)一律归零,避免计数与新查询错位;
  3. 计数语义严格绑定替换结果:单次替换以 replaceAndSelectNext 的成功返回为条件 +1;全部替换直接采用 replaceAll 引擎返回的替换次数,两处都由 common 层单元测试兜底;
  4. 跨产品线文案对齐:find.replacedPrefix / find.foundPrefix 在 Compose 与 Electron 两侧使用同一文案体系,且支持中、英、日三语;
  5. 向后兼容:Json { ignoreUnknownKeys = true } + 快照字段默认值,使新增字段对旧数据无损。

对于需要自行实现「查找/替换条」状态的产品,这套「会话字段 + snapshot/restore + 引擎返回次数 + 四时机归零 + round-trip 测试」的组合,是一个可以直接参照的完整模式。

登录后查看全文
MooTool