MooTool Next Compose:设置页与配置转换分栏的 Electron 布局迁入实践(DIFF-168 解析)

原创2026-10-14 12:17:161,815 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool Next Compose:设置页与配置转换分栏的 Electron 布局迁入实践(DIFF-168 解析)

本篇技术指南围绕 MooTool Next Compose 桌面版的一份功能规格 DIFF-168,完整讲解 Electron 端窗格尺寸(pane sizes)如何被迁入 Compose 端:设置页左侧分类导航两列布局、以及配置转换工具中「转换 / 校验」两个 Tab 的三列 IO 布局,都通过归一化比例换算、写入 layout.paneSizes 持久化。读完本文,你将掌握 Electron storageKey 与 Compose paneSizes 两套布局存储模型之间的映射规则、换算公式与边界约束,并了解对应的 UI 消费方式与测试验证方法。

背景:两套布局存储模型为什么要统一

MooTool 的 Electron 实现与 Compose(Kotlin/Compose Multiplatform)实现是同一产品家族的两条技术栈。两者对「可拖拽分栏宽度」的持久化方式存在根本差异:

  • Electron 在 ResizableColumns 组件中,把分栏宽度归一化为比例数组(ratios),以 storageKey 作为存储键写入本地存储。例如设置页两列默认 [220, 780]、配置转换三列默认 [1, 0.28, 1]。
  • Compose 则按「工具 ID + 分栏索引」在 layout.paneSizes 中保存绝对 dp 宽度(Float),见 Settings.kt。

DIFF-168 要解决的历史问题是:Compose 此前固定了设置导航宽度 220dp、配置页固定中栏宽度,迁入流程没有覆盖 settings-page / config-convert / config-validate 这三个存储键,导致用户从 Electron 迁移到 Compose 时,这几个窗口的分栏布局无法继承。

行为规格:三个新增键与两个统一映射函数

DIFF-168 定义了三个验收行为:

编号 行为 写入位置
A01 设置页左侧分类导航可拖拽,宽度写入 layout.paneSizes<a href="https://link.gitcode.com/i/b0449038f6d4098df2623da92b3126dc" target="_blank">"settings-page"] 索引 0 [SettingsScreen.kt
F06 转换与校验两个 Tab 均为三列可拖(双手柄),分别写入 config-convert / config-validate 索引 0、1 ConfigConvertScreen.kt
A03 ElectronPaneSizeImport 新增上述三键映射;mapIoThreePane / mapTwoColumnWorkspace 统一使用字符串 pane key(与 Electron storageKey 一致) ElectronPaneSizeImport.kt

验收项目编号与 docs/acceptance.md 的 A01(12 类设置)、F06(配置转换)、A03(桌面/存储/备份/Git/更新)对应,见 acceptance.md。

三键映射的完整参数表

以下参数均来自 ElectronPaneSizeImport.kt 的实际代码,可直接对照:

A01:设置页 settings-page

mapTwoColumnWorkspace(
    electron["settings-page"],   // Electron 两列比例,默认 [220, 780]
    "settings-page",             // 字符串 pane key(对齐 Electron storageKey)
    180f, 360f,                  // 第一列 min / max(dp)
    420f,                        // 第二列默认宽度(dp,沿用现有值)
    result, current
)
  • 参考宽度基准:REFERENCE_CONTENT_WIDTH_DP = 1320f。
  • 换算公式:第一列宽度 = ratios[0] / (ratios[0] + ratios[1]) × 1320,结果再 coerceIn(180f, 360f)。
  • 第二列不强制覆盖,优先取当前 Compose 已有值,缺失时才回退到默认 420dp(见下文 existingSlot 规则)。

F06:配置转换 config-convert 与 config-validate

mapIoThreePane(electron["config-convert"],  "config-convert",  240f, 700f, 110f, 280f, result)
mapIoThreePane(electron["config-validate"], "config-validate", 240f, 700f, 110f, 280f, result)

三列比例换算(mapIoThreePane):

val left   = ratios[0] / total * 1320f   // coerceIn(minLeft=240f, maxLeft=700f)
val middle = ratios[1] / total * 1320f   // coerceIn(minMiddle=110f, maxMiddle=280f)
result[paneKey] = listOf(left, middle)   // 第三列 = 剩余空间(weight 自适应)

对应 Electron 端默认值(见 ConfigConvertTool.tsx):

存储键 列数 Electron 默认比例 Electron 最小宽
config-convert 3 [1, 0.28, 1] [240, 110, 240]
config-validate 3 [1, 0.32, 0.6] [240, 110, 220]
settings-page 2 [220, 780] [180, 420]

底层原理:比例 → dp 的归一化换算

mergeElectronIntoCompose 的整体输入输出签名:

fun mergeElectronIntoCompose(
    electron: Map<String, List<Float>>,  // Electron storageKey → 比例数组
    current: Map<String, List<Float>>    // Compose 现有 paneSizes
): Map<String, List<Float>>             // 合并后的 paneSizes

换算核心逻辑(mapTwoColumnWorkspace):

val total = ratios.sum().takeIf { it > 0f } ?: return  // 比例和 ≤ 0 直接跳过
val first = (ratios[0] / total * REFERENCE_CONTENT_WIDTH_DP)
    .coerceIn(minFirst, maxFirst)                       // 归一化到参考宽度并夹取边界
val second = existingSlot(result, current, paneKey, 1, defaultSecond)
result[paneKey] = listOf(first, second)

其中 existingSlot 是「已存在优先」策略:

private fun existingSlot(...): Float =
    result[paneKey]?.getOrNull(index)      // 1. 本次合并结果里已有
        ?: current[paneKey]?.getOrNull(index) // 2. 当前 Compose 设置里已有
        ?: fallback                            // 3. 兜底默认值

也就是说,mapTwoColumnWorkspace 只迁移第一列(主导列)的比例宽度,第二列尽量保留 Compose 用户已调整的宽度,避免破坏既有偏好;而 mapIoThreePane 则同时迁移左列与中列两个可拖手柄控制的槽位。

消费侧 UI:拖拽手柄如何读写 paneSizes

设置页(A01)

SettingsScreen.kt 中:

  • 常量 SETTINGS_PANE_KEY = "settings-page";
  • 导航宽度读取:settings.layout.pane(SETTINGS_PANE_KEY, 0, defaultNav, minNav, maxNav),其中 minNav = 180f、minContent = 420f、手柄宽 10f;
  • 拖拽写入:VerticalPaneHandle(onDelta = { container.setPaneSize(SETTINGS_PANE_KEY, 0, navWidth + it, 1) }, ...),双击重置回默认宽度。

配置转换(F06)

ConfigConvertScreen.kt 通过统一的 ConfigIoPanes → IoThreePaneRow(IoPaneLayouts.kt)渲染三列:

  • 转换 Tab:paneKey = "config-convert"、middleRatio = 0.28f、minRight = 240f;
  • 校验 Tab:paneKey = "config-validate"、middleRatio = 0.32f、minRight = 220f。

IoThreePaneRow 内部使用两个 VerticalPaneHandle(双手柄),分别把左列、中列宽度写回 paneSizes<a href="https://link.gitcode.com/i/37edb0b0db5f8386bbcc95aab5d35de3" target="_blank">paneKey] 索引 0、1,右列占剩余权重;手柄组件 [PaneResizeHandle.kt 中 setPaneSize 最终调用 LayoutSettings.withPane 写入持久化设置。

关键点:设置页是「两列 + 单手柄」只写索引 0,配置转换是「三列 + 双手柄」写索引 0、1——这正好对应 A01 与 F06 行为描述,也与 mapTwoColumnWorkspace / mapIoThreePane 两种映射策略一一对应。

持久化与校验:sanitizePaneSizes 的约束

Compose 端写入前的统一清洗由 SettingsLayoutNormalize.kt 的 sanitizePaneSizes 完成,可视为迁入数据的安全兜底:

  • pane key 必须匹配 ^[a-z0-9-]{1,64}$(大小写不敏感),超长或非法字符键被丢弃;
  • 每个键的值长度必须落在 2..4(两列/三列/四列布局);
  • 所有值必须为有限正数(!isFinite() || <= 0f 即丢弃);
  • 最多保留 64 个 pane 键。

因此在 mergeElectronIntoCompose 换算出绝对 dp 宽度之后,整个 paneSizes 还会经过这一层归一化,确保迁移数据不会污染本地配置。

验证:测试用例与回归命令

DIFF-168 指定的验证用例如下(ElectronPaneSizeImportTest.kt):

@Test
fun convertsSettingsPageAndConfigPaneRatios() {
    val merged = ElectronPaneSizeImport.mergeElectronIntoCompose(
        mapOf(
            "settings-page" to listOf(220f, 780f),
            "config-convert" to listOf(1f, 0.28f, 1f),
            "config-validate" to listOf(1f, 0.32f, 0.6f)
        ),
        emptyMap()
    )
    assertEquals(290.4f, merged["settings-page"]!![0], 0.5f)   // 220/1000 × 1320 = 290.4
    val convert = merged["config-convert"]!!
    assertEquals(578.947f, convert[0], 0.5f)                    // 1/2.28 × 1320 ≈ 578.95
    assertEquals(162.105f, convert[1], 0.5f)                    // 0.28/2.28 × 1320 ≈ 162.11
    val validate = merged["config-validate"]!!
    assertEquals(687.5f, validate[0], 0.5f)                     // 1/1.92 × 1320 = 687.5
    assertEquals(220f, validate[1], 0.5f)                       // 0.32/1.92 × 1320 = 220
}

该用例同时验证了换算公式的正确性(比例归一化到 1320dp 参考宽度)与边界夹取的有效性。回归命令:

./gradlew :composeApp:desktopTest --offline

当前仓库的完整测试集同样包含该文件所在包(ElectronPaneSizeImportTest、ElectronNextSettingsImport 相关用例),验收记录见 acceptance.md。

小结:一套可复用的跨栈布局迁移范式

从 DIFF-168 可以看到 MooTool Next Compose 的跨栈迁移设计范式:

  1. Electron 侧以 storageKey + 比例数组持久化分栏(如 [1, 0.28, 1]);
  2. Compose 侧以「pane key + 索引」持久化绝对 dp 宽度;
  3. 映射层 ElectronPaneSizeImport 用 mapTwoColumnWorkspace / mapIoThreePane 按参考宽度 1320dp 归一化换算,并配 coerceIn 边界保护与 existingSlot 保留既有偏好;
  4. 清洗层 sanitizePaneSizes 兜底校验键名与数值合法性;
  5. UI 层 VerticalPaneHandle 拖拽写回,双击重置默认;
  6. 测试层以比例输入断言 dp 输出,锁定换算公式。

这套「字符串 pane key + 比例归一化 + 边界夹取 + 清洗兜底」的链路,不只是针对设置页与配置转换,在 DIFF-163~172 等系列变更中同样被复用到 JSON、文本对比、编码解码、Protobuf、加解密、二维码、随手记等所有可拖分栏工具,是整个 Compose 版对 Electron 布局资产迁移的通用基础设施。

登录后查看全文
MooTool