MooTool next-compose Host 查找条导航(DIFF-277)实现解析:上一处/下一处跳转、选项开关与替换语义对齐

原创2026-10-15 20:40:381,922 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool next-compose Host 查找条导航(DIFF-277)实现解析:上一处/下一处跳转、选项开关与替换语义对齐

Host 编辑器是 MooTool 开发者工具箱中最常用、也最容易出错的功能之一:既要维护 /etc/hosts 配置文件,又要在成百上千行条目中快速定位目标域名并完成批量调整。next-compose(Compose Multiplatform 桌面版)针对 Host 正文编辑器补齐了完整的查找/替换交互——上一处/下一处跳转、区分大小写/全词/正则三项选项开关、基于正文光标而非固定位置的替换语义,以及无匹配提示。本篇以演进记录 DIFF-277 文档 为骨架,结合 Electron 参照实现与 Compose 端源码、测试,逐层拆解这套查找条的导航算法、UI 装配和键盘交互,读者可直接对照源码验证每一个行为。

背景:为什么需要 DIFF-277

next-compose 是 MooTool 的 Compose Multiplatform 桌面重构版(参见 next-compose/README.md),目标是在保持既有 Electron 版 next 功能基线的前提下,用 Kotlin/Compose 重写全部工具页。Host 工具的查找条属于"交互细节密集"的功能,任何一处跳转起点、选区更新或替换锚点的偏差,都会直接影响用户编辑体验。

对照 Electron 版的 HostTool,其查找条直接复用通用组件 FindReplaceBar(源码见 FindReplaceBar.tsx),并配合工具内 findAround(forward) 实现"在正文中选中下一处/上一处匹配",同时支持 matchCase/wholeWord/regex 三项选项,替换则基于当前选区或光标位置(见 HostTool.tsx)。DIFF-277 的目标就是把这一整套行为原样移植到 Compose 端,消除两个客户端在查找导航上的行为落差。

DIFF-277 定义的行为清单

原文档将本次差异收敛为三个可验证的行为点:

  1. HostFindNavigation.jump 统一跳转入口:根据 TextFieldValue 的当前选区位置,调用领域层的 FindReplace.findNext 计算下一处/上一处匹配,并把结果写回 TextFieldValue.selection,实现正文中的选中跳转。
  2. FindBar 补齐完整交互:Host 查找条补齐"上一处/下一处"按钮、三项选项开关(matchCase/wholeWord/regex);replaceCurrent 使用正文中的光标(caret)作为替换起点,而不是固定的索引 0——这一条是修复此前替换总是从文首开始找匹配的偏差。
  3. 无匹配反馈:当查找词非空但找不到匹配时,写入状态栏提示 json.notice.noMatches("未找到匹配内容")。

这三个点分别对应导航算法、UI 装配、错误反馈三条主线,下面逐一展开源码实现。

导航核心:HostFindNavigation 与 FindReplace 领域层

HostFindNavigation.jump:基于选区的跳转

跳转的单一入口定义在 HostFindNavigation.kt:

fun jump(
    content: String,
    query: String,
    options: FindReplaceOptions,
    field: TextFieldValue,
    forward: Boolean,
): TextFieldValue? {
    val selection = field.selection
    val fromIndex = if (forward) {
        maxOf(selection.start, selection.end)
    } else {
        minOf(selection.start, selection.end)
    }
    val match = FindReplace.findNext(content, query, options, fromIndex, forward) ?: return null
    return field.copy(selection = TextRange(match.start, match.end))
}

关键细节在于 fromIndex 的计算:向前查找取选区的 max(末尾),向后查找取选区的 min(起点)。这保证了从光标出发时方向正确,从一段选中文本出发时也不会因为选区内部的偏移而漏掉相邻匹配。找不到匹配时返回 null,由 UI 层统一触发无匹配提示。

领域层 FindReplace:匹配的查找与换行回绕

匹配引擎位于公共模块 FindReplace.kt,对 Electron 版 findReplace.ts(next/src/shared/components/findReplace.ts)做了 Kotlin 移植:

  • findAll 用正则遍历全文收集所有 FindMatch(start, end),并显式跳过空匹配(零宽匹配会导致死循环);
  • findNext(content, query, options, fromIndex, forward) 在匹配列表中做方向查找:向前取 start >= fromIndex 的首个匹配,找不到则回绕到第一个(matches.first());向后取 end <= fromIndex 的末个匹配,找不到则回绕到最后一个。这一"循环回绕"语义与 Electron 的 findNextMatchWithWrap 完全一致。

选项通过 FindReplaceOptions(matchCase/wholeWord/regex,默认均为 false)传递,正则构造逻辑为:非正则模式先 Regex.escape(query) 转义再匹配;wholeWord 开启时用 \b(?:source)\b 包裹;matchCase 关闭时追加 RegexOption.IGNORE_CASE。这些规则与 Electron 版 buildSearchRegExp 一一对应,保证两端对同一查询串的行为一致。

当前匹配判定 findMatchAtSelection

HostFindNavigation.currentMatch 委托编辑器模块的 findMatchAtSelection:先尝试精确命中与选区完全重合的匹配,其次返回"选区起点落在其区间内"的匹配。它用于高亮渲染时区分"当前匹配"(强调色)与"其余匹配"(淡色),交互语义上对应 Electron 代码编辑器的 codeEditorSearchHighlight。

查找条 UI:上一处/下一处、三项选项与替换锚点

FindBar 的完整装配

Host 页的查找条是 HostScreen.kt 内的私有 Composable FindBar,从左到右依次为:查找输入框、查找按钮、替换输入框、matchCase/wholeWord/regex 三个选项开关、命中数(find.foundPrefix)、上一处、下一处、替换、全部替换、已替换数(find.replacedPrefix)与关闭按钮。

跳转动作统一收敛到局部函数 jumpFind(forward):

fun jumpFind(forward: Boolean) {
    if (session.findQuery.isBlank()) return
    HostFindNavigation.jump(session.content, session.findQuery, session.findOptions, contentField, forward = forward)
        ?.let(onContentFieldChange)
        ?: run { container.toastFindNoMatches() }
    onChanged()
}

查询词为空时直接短路;有匹配则把新的 TextFieldValue(含更新后的选区)回写到正文输入框;无匹配则走 toastFindNoMatches()。

三个选项开关是典型的"按钮即开关"交互:点击后对 findOptions 做 copy(...) 翻转并重置已替换计数 findReplacedCount = 0,按钮文案实时展示状态(例如 区分大小写: false)。对应 i18n 文案见 Translator.kt(find.matchCase/find.wholeWord/find.regex,中英日三语齐备)。

replaceCurrent:使用正文光标而非固定 0

本次差异的核心修复点在替换按钮的回调(HostScreen.kt):

val selection = contentField.selection
val caret = maxOf(selection.start, selection.end)
val (next, match) = FindReplace.replaceCurrent(
    session.content,
    session.findQuery,
    session.replaceText,
    session.findOptions,
    caret,
    selection.start,
    selection.end,
)

替换起点 caret 取自正文 TextFieldValue.selection 的末端——这正是文档强调的"使用正文光标而非固定 0"。领域层 FindReplace.replaceCurrent 的语义为:若当前选区完整等于一处匹配(selectionEnd > selectionStart 且选区内恰好只有 1 个全覆盖匹配),则替换该选区;否则从 fromIndex 起找下一处匹配并替换。这与 Electron 版 replaceCurrentMatch 的"先选区、后查找"策略完全对齐。

替换成功后,调用 HostFindNavigation.afterReplaceAndSelectNext(见 HostFindNavigation.kt):写入替换后的正文,并从被替换区间的末尾继续向前 findNext,把下一处匹配自动选中。这与 Electron HostTool.replaceCurrent(false) 用 findNextMatch(..., result.nextFrom, true) 选中下一处的行为一致(相关演进记录见 DIFF-278)。

无匹配反馈:json.notice.noMatches

DIFF-277 文档要求"无匹配时状态栏 json.notice.noMatches"。在实现层面,AppContainer.toastFindNoMatches() 通过 info toast 弹出本地化文案 find.noMatches(中英日分别对应"未找到匹配内容 / No matches found / 一致する内容がありません",见 AppContainer.kt 与 Translator.kt);json.notice.noMatches 这个 key 在同文件中也承担着 Host 配置列表为空时的"无匹配"占位文案(HostScreen.kt)。同一字符串在查找无命中场景的展示路径,与 Electron 端 toast.info(t('findReplace.noMatches')) 对应(HostTool.tsx)。

高亮渲染:匹配与当前项的可视化

查找条打开且查询非空时,HostScreen 用 remember 缓存 FindReplace.findAll 的结果,并构造 FindHighlightTransformation 作为正文输入框的 VisualTransformation:所有命中以 accent.copy(alpha = 0.24f) 打底,当前匹配以 accent.copy(alpha = 0.52f) 高亮(HostScreen.kt)。由于正文使用 MooTextField(TextFieldValue) 承载并保留选区,高亮、光标与跳转三者的选区状态可以始终同步。

键盘交互:对齐 Electron FindReplaceBar

DIFF-277 之外,查找条的行级快捷键由编辑器模块 FindBarKeyHandling.kt 统一提供(配套演进记录见 DIFF-280):

  • 查找条内 ↑ / ↓:上一处 / 下一处(FindBarKeyAction.Previous/Next);
  • 查找条内 Escape:关闭查找条;
  • 查找输入框 Enter:查找下一处(previewFindQueryEnter 同时接受 Enter 与 NumPadEnter);
  • 打开查找条时通过 FocusRequester 自动聚焦查找输入框。

所有这些按键处理都做了 IME 输入法守卫:blockedByIme() 时一律返回 None,避免中文输入法组合键被误当作查找快捷键。Host 的 FindBar 通过 onFindBarRowKeys 与 onFindQueryEnterKey 两个 Modifier 扩展接入这套策略(HostScreen.kt)。

测试与验证

单元测试 HostFindNavigationTest

DIFF-277 的验证主体是 HostFindNavigationTest.kt,三个用例分别锁定三条行为:

  • jump_selects_next_match_from_caret:对 "aa bb aa",光标置于索引 3,jump(..., forward = true) 应选中索引 6..8 的第二处 aa——验证基于光标的前向跳转与选区写入;
  • replaceCurrent_updates_selection_to_replacement:替换 "hello" 中 2..4 区间后,正文变为 "heXXo" 且选区更新为 2..4——验证替换后的选区收敛到替换产物上;
  • afterReplaceAndSelectNext_advances_to_following_match:替换首处 "aa" 为 "XX" 后,自动把选区推进到下一处 aa(索引 3..5)——验证"替换后选中下一处"的连锁行为。

与之配套的领域层测试是公共模块的 FindReplaceTest.kt,覆盖 findNext 的方向与回绕、replaceCurrent 的选区优先策略、replaceAll 的批量替换以及正则替换模板 $1/$&、转义 \n/\t/\r 的展开逻辑。

运行命令

文档指定的验证命令为(在 next-compose 目录下执行,--offline 表示不访问网络依赖,可直接复用本地 Gradle 缓存):

./gradlew :composeApp:desktopTest --offline

该命令运行 desktopTest 源码集下全部桌面端测试(含 HostFindNavigationTest),公共模块测试则随 commonTest 一并执行。

相关演进脉络

DIFF-277 并非孤立改动,而是 Host 查找条系列对齐工作的一环,仓库 next-compose/docs/diff/ 目录下保留了完整演进记录,可按序阅读:

  • DIFF-276:打开查找时用正文选区预填查找框(selectedTextForFind),并让 Host 正文改用 TextFieldValue 保留选区;
  • DIFF-278:单次替换后自动选中下一处匹配;
  • DIFF-280:查找条行级键盘(↑/↓/Esc/Enter)与自动聚焦;
  • DIFF-288:查找条"已替换"计数与"共找到"文案统一;
  • 无匹配提示在 JSON、HTTP 等工具的落地方案见 DIFF-283 与 DIFF-290。

小结

DIFF-277 的核心价值在于把 Electron FindReplaceBar 的导航与替换语义精确落到 Compose 端:HostFindNavigation.jump 以 TextFieldValue 选区为锚点驱动 FindReplace.findNext 的方向查找;replaceCurrent 以正文光标(caret)而非固定索引 0 定位替换起点,并在替换后自动推进到下一处;三项选项开关(区分大小写/全词/正则)与无匹配提示 json.notice.noMatches 补齐了与 Electron 的交互一致性。从领域层的 FindReplace.kt 到 UI 层的 FindBar,再到键盘层的 FindBarKeyHandling,每一层都有对应的测试用例守护,读者可直接运行 ./gradlew :composeApp:desktopTest --offline 验证全部行为。

登录后查看全文
MooTool