MooTool Next Compose 查找条「已替换」计数实现解析:会话持久化、归零时机与单次/全部替换语义
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.ktL89 / L114):// 快照侧(默认值保证旧快照可反序列化) val findReplacedCount: Int = 0, // 运行时侧 var findReplacedCount: Int = 0QuickNoteSessionSnapshot/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()
}
})
两个细节值得注意:
- 成功才计数:
replaceAndSelectNext返回false表示无匹配可替换,此时走toastFindNoMatches()分支,计数不变;只有真正执行了一次替换并选中下一处,才执行findReplacedCount += 1。 - 配套状态清理:替换成功后同步清空 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,与 ElectronapplyReplacement对齐)。
在 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 及其配套源码可以总结出这套「已替换计数」的实现要点:
- 计数归属会话而非组件:
findReplacedCount放在JsonSession/QuickNoteSession/HostSession上,随快照持久化到 SQLite,工具切换、应用重启后计数与查找词/选项一并恢复; - 归零是交互契约:凡是「匹配结果可能变化」的交互(打开、改词、改选项、关闭)一律归零,避免计数与新查询错位;
- 计数语义严格绑定替换结果:单次替换以
replaceAndSelectNext的成功返回为条件+1;全部替换直接采用replaceAll引擎返回的替换次数,两处都由 common 层单元测试兜底; - 跨产品线文案对齐:
find.replacedPrefix/find.foundPrefix在 Compose 与 Electron 两侧使用同一文案体系,且支持中、英、日三语; - 向后兼容:
Json { ignoreUnknownKeys = true }+ 快照字段默认值,使新增字段对旧数据无损。
对于需要自行实现「查找/替换条」状态的产品,这套「会话字段 + snapshot/restore + 引擎返回次数 + 四时机归零 + round-trip 测试」的组合,是一个可以直接参照的完整模式。