MooTool Next Compose 窗口恢复夹回、JSON 复制反馈、图片工具栏溢出收纳与 Git 多文件差异:设计与 231 项测试验证
MooTool Next Compose 窗口恢复夹回、JSON 复制反馈、图片工具栏溢出收纳与 Git 多文件差异:设计与 231 项测试验证
导读
本文围绕 MooTool Next Compose(Compose Multiplatform Desktop 独立产品线)在 2026-09-15 完成的一批跨模块体验对齐展开:窗口恢复时坐标夹回可见工作区、JSON 复制按钮的短暂状态反馈、图片助手工具栏在 1080 宽度下的「更多」收纳,以及 Vault Git 提交差异的多文件选择。文中既有可直接照搬的配置与运行命令,也逐条对应源码实现与测试用例,帮助你理解这套桌面工具如何在无真实显示器环境下用纯逻辑测试守住窗口、复制、溢出与 Git 差异的边界行为。证据记录见 results.md,决策依据见 DIFF-044。
背景:四个体验差异的来源与影响范围
本次变更源于 MooTool 的 UI/交互规格(docs/ui-spec.md)中对两处硬要求的补充:更换显示器后要把可操作的标题区夹回可见范围,以及复制操作后需要短暂反馈。同时,图片工具栏在 1080 宽度下水平堆满,Git 提交预览此前只展示第一个文件,这两处也需要补齐。
按 DIFF-044 的登记,本次影响面覆盖四个功能域:
| 影响域 | 对应功能 | 变更内容 |
|---|---|---|
| A03 窗口恢复 | Workbench | 启动时按各显示器工作区夹紧保存的窗口坐标 |
| F04 JSON | 复制按钮 | 成功显示「已复制」、失败显示失败文案,约 1400ms 后复位 |
| F23 图片 | 工具栏 | 内容宽 < 1440 时次要操作收入「更多」下拉 |
| F01/F04 Vault Git | 提交差异 | 加载该提交全部文件,多于一个时用下拉切换 |
对照的 Electron 原行为是:恢复窗口时 Chromium 尽量把窗口留在可用屏幕;JSON 复制按钮在复制后短暂变为「已复制」/失败文案;图片助手工具栏 1080 宽时动作过密;Git 提交差异在多文件时使用下拉选择而非只看第一个文件。
窗口恢复夹回:WindowBoundsPolicy 的坐标夹紧算法
设计要点
- 已保存坐标只要还在屏内就原样保持,不做无谓的居中;
- 窗口在第二屏上就留在第二屏,不拉回主屏;
- 标题条至少 48px 落在某个工作区内才认为“可见”,否则按最近工作区夹回;
- 标题在屏幕上方时夹回工作区顶部;
- 无任何屏幕信息(headless)时保留已保存坐标,绝不擅自居中——这是与 Electron“无脑居中”的关键差异。
源码实现
核心实现在 WindowBoundsPolicy.kt,关键常量如下:
object WindowBoundsPolicy {
const val TITLE_BAR_HEIGHT = 28 // 标题条高度,用于可见性判定
const val MIN_TITLE_VISIBLE = 48 // 标题条最少可见宽度(px)
const val MIN_WIDTH = 960 // 最小窗口宽
const val MIN_HEIGHT = 640 // 最小窗口高
...
}
clamp(x, y, width, height, screens) 的判定顺序很清晰:
- 宽高先做
coerceAtLeast(MIN_WIDTH/MIN_HEIGHT)下限保护; x或y为 null(从未保存过)时返回 null 坐标,由上层交给WindowPosition(Alignment.Center)处理居中;- 屏幕列表为空,或任一屏幕满足
titleBarVisible(...)(标题条横向重叠 ≥ 48px 且纵向有交集)时,直接返回原坐标; - 否则用
nearestPointDistanceSquared找出最近工作区,把坐标coerceIn到该工作区减去标题区余量后的范围内。
工作区(work area,即扣除任务栏/Dock 后的可用区域)通过 AWT 获取,见 currentWorkAreas():遍历 GraphicsEnvironment.getLocalGraphicsEnvironment().screenDevices,用 Toolkit.getDefaultToolkit().getScreenInsets(configuration) 扣除系统 UI 占用;无 headless、尺寸非法等情况一律返回空列表,走“保留坐标”分支。
与主窗口的集成
Main.kt 在 remember 中一次性计算恢复位置,再构造 rememberWindowState;坐标来自设置里的 workspace.windowX/Y/Width/Height,而 persistBounds() 在窗口移动时反向写回设置。同时保留了 settings.general.startMaximized 的最大化优先级。
测试覆盖:六种边界场景
WindowBoundsPolicyTest.kt 用两组固定工作区(主屏 (0,0,1920,1080)、第二屏 (1920,0,1920,1080))逐条验证:
| 测试方法 | 输入坐标 | 断言 |
|---|---|---|
missingPositionCentersWithMinimumSize |
x/y 为 null,800×500 | 坐标仍为 null,尺寸抬到 960×640 |
onScreenBoundsStayUnchanged |
120,80,1440×920 | 原样保留 |
secondMonitorStaysOnSecondMonitor |
2000,100 | 仍在第二屏,不拉回主屏 |
offScreenTitleBarClampsIntoNearestWorkArea |
5000,100 | x 夹到 1920 - 48 |
titleBarAboveScreenClampsDown |
100,-200 | y 夹到 0 |
emptyScreensKeepSavedCoordinates |
40,50 | 无屏幕时坐标不变 |
六条用例正好对应 evidence 文档里“已保存坐标在屏内保持;第二屏不拉回主屏;完全越界夹到最近工作区;标题在屏幕上方夹回;无屏幕信息时保留原坐标”的验收清单。
JSON 复制反馈:CopyFeedbackPolicy 的三态文案与 1400ms 复位
状态机与文案键
JSON 复制按钮 的反馈完全由 CopyFeedbackPolicy.kt 驱动:
object CopyFeedbackPolicy {
const val IDLE = "idle"
const val COPIED = "copied"
const val FAILED = "failed"
const val RESET_MS = 1400L
fun afterCopy(success: Boolean): String = if (success) COPIED else FAILED
fun buttonKey(state: String, idleKey: String = "json.action.copy"): String = when (state) {
COPIED -> "json.action.copied"
FAILED -> "json.notice.copyFailed"
else -> idleKey
}
}
buttonKey 支持自定义 idle 文案键(默认 json.action.copy),因此同样能被格式化页(reformat.copy)复用;idleKey 只在 IDLE 状态生效,COPIED/FAILED 的键不受影响。文案在多语言表中有登记,例如中文下 json.action.copied → “已复制”、json.notice.copyFailed → “复制失败”、json.action.copy → “复制”,见 Translator.kt。
1400ms 复位与失败仍写 notice
JsonToolbar 里用 LaunchedEffect(session.copyGeneration, session.copyState) 实现复位:状态非 IDLE 时 delay(CopyFeedbackPolicy.RESET_MS) 后回到 IDLE 并触发 onChanged()。复制点击处同时把 copyText(...) 返回的 outcome.notice 写入 session.notice,所以剪贴板失败时按钮文案与状态栏 notice 双通道反馈,且反馈状态不写入会话快照(DIFF-044 受影响范围第 2 条)。
CopyFeedbackPolicyTest 的 copiedAndFailedResetAfterElectronDelay 用例锁定了 RESET_MS == 1400、afterCopy(true/false) 的映射、以及三态 buttonKey(含空字符串回退到 idle、自定义 reformat.copy 仅影响 IDLE)这组行为,见 CopyFeedbackPolicyTest.kt。
图片工具栏 1080 溢出:LayoutPolicy 与「更多」下拉
溢出阈值
工具栏溢出判定集中在 LayoutPolicy.kt:
object LayoutPolicy {
const val FULL_TOOLBAR_WIDTH_DP = 1440f
fun overflowToolbar(contentWidthDp: Float): Boolean = contentWidthDp < FULL_TOOLBAR_WIDTH_DP
}
BoxWithConstraints 下的内容实际宽度小于 1440dp 即进入溢出模式。同一策略被 JSON、Host、Net、Cron、时间转换等大量工具页共享,图片页只是其一。
保留项与收纳项
图片页工具栏在 ImageScreen.kt 中按 overflow 分支渲染。在 1080 宽度下:
- 始终保留:列表开关(显示/隐藏列表)、截图、导入、保存、复制,以及进行中的「取消」;
- 收入「更多」下拉:从剪贴板、从 Base64、转 SVG、压缩、水印、转 Base64、历史、分离(detach)等次要操作,统一通过「更多」按钮 +
MooMenu弹出,每个菜单项复用ImageWiringPresentation的启用条件判断。
这种“高频操作常驻、低频操作收纳”的分层,与 045-reformat-color-overflow 对格式化页/调色板的处理一致(格式化页保留 Tab/类型/缩进/格式化,把复制/保存/清空收进「更多」)。需要说明的是,图片页工具栏本身叠加了 horizontalScroll,溢出菜单解决的是“动作过密”的组织问题,而非单纯滚动。
Vault Git 提交差异:多文件加载、路径选择与重命名标签
fileDiffs 支持提交维度
GitEngine.fileDiffs 同时支持工作区与提交两种维度:commit 参数非空且通过 COMMIT_HASH 校验后,转入 commitDiffFiles(root, commit, path, isolateConfig)。
commitDiffFiles(同文件 L289-L309)的实现要点:
- 用
git rev-parse --verify <commit>^求父提交; - 有父提交走
git diff --name-status -z -M -C parent commit,无父提交(根提交)走git diff-tree --root --no-commit-id --name-status -z -r -M -C commit,两者都带-M/-C以正确识别重命名与复制; -z输出由parseNameStatus解析为GitChange列表;- 对每个变更,用
git cat-file读取父提交与提交两个 blob 的预览内容,超过MAX_DIFF_PREVIEW_BYTES(512 KB)标为too-large、含 NUL 字节标为binary,最终落入GitFileDiff(path, originalPath, status, before, after, preview),见同文件readBlobPreview与toFileDiff(L311-L348)。
下拉选择与重命名标签
- GitDiffSelection.kt 提供
fileLabel("$status $path",重命名时拼成status old → new,状态为空回退M)与selected(files, selectedPath)(按路径命中,否则回退第一个文件); - GitDiffPresentation.kt 决定
showFilePicker(fileCount > 1)、二进制/超大文件提示文案与 RSTA 语法高亮; - 差异区 UI 在 VaultGitDialog.kt:多于一个文件时,当前文件以按钮形式显示
GitDiffSelection.fileLabel(fileDiff),点击弹出MooMenu列出全部文件标签;仅单个文件时直接展示标签文本。选中文件后进入DiffEngine.compare(before, after, ignoreWhitespace = false)的并排 diff 预览,语言/语法键通过文件后缀由TextCodeEditorLanguages解析。
测试验证
GitEngineTest.commitDiffListsAllChangedFiles(GitEngineTest.kt)构造了包含 a.md、b.md 两次修改的真实提交,断言 fileDiffs(root, commit = latest.hash) 返回 2 个文件、路径集合为 {a.md, b.md}、各自 before/after 正确,并能用 GitDiffSelection.selected(files, "b.md") 按路径选中。
GitDiffSelectionTest.labelsRenameAndFallsBackToFirstFile(GitDiffSelectionTest.kt)验证:
- 普通修改标签
M a.md; - 重命名标签
R100 b.md → c.md; - 无状态文件回退
M; - 按路径命中与“找不到时回退第一个文件”、空列表返回 null。
验证方法:desktopTest 231/231 全绿
证据文档记录了可复现的验证命令(运行前提是本机已装 JDK 21 与 Git):
JAVA_HOME="$(/usr/libexec/java_home -v 21)" ./gradlew :composeApp:desktopTest --offline
- 结果:
desktopTest231/231(0 skipped / 0 failed); - 记录环境:macOS Darwin 25.6.0 x86_64,Zulu 21;
- 本次新增覆盖与验证路径:
WindowBoundsPolicyTest、CopyFeedbackPolicyTest、GitDiffSelectionTest、GitEngineTest.commitDiffListsAllChangedFiles。
尚未覆盖的项
证据文档同时如实标注了仍属“未测”的清单,这些无法靠纯逻辑测试收敛,需要真实环境人工验收:
- 真实多显示器插拔后启动窗口位置;
- JSON 复制按钮在运行窗口中的 1400ms 观感与焦点保留;
- 图片 1080 工具栏「更多」窗口截图;
- Git 对话框内多文件下拉手工切换;
- IME/列编辑手工、托盘权限、三平台安装。
这也解释了为何窗口坐标夹紧这类逻辑用纯 AWT 工作区模型 + 六个单测兜底,而把观感类验收留给后续人工证据。
总结
这次变更把四类原本依赖运行时环境的体验差异,收敛为可单测的纯策略:窗口夹回靠 WindowBoundsPolicy.clamp 的几何判定、复制反馈靠 CopyFeedbackPolicy 的三态状态机与 1400ms 复位、图片工具栏溢出靠 LayoutPolicy.overflowToolbar 的 1440dp 阈值、Git 多文件差异靠 GitEngine.commitDiffFiles 的 name-status 解析与 GitDiffSelection 的标签/选择逻辑。在此基础上用 231 项 desktopTest 锁定行为边界,并诚实保留多显示器插拔、真实窗口观感、截图与三平台安装等手工验收项。
如需深入,可继续阅读 DIFF-044 决策记录、图片溢出相关的 045 记录、LayoutPolicy 溢出与紧凑布局策略以及 UI 与交互规格。