MooTool Next Compose:设置页与配置转换分栏的 Electron 布局迁入实践(DIFF-168 解析)
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)
- 常量
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 的跨栈迁移设计范式:
- Electron 侧以
storageKey+ 比例数组持久化分栏(如[1, 0.28, 1]); - Compose 侧以「pane key + 索引」持久化绝对 dp 宽度;
- 映射层
ElectronPaneSizeImport用mapTwoColumnWorkspace/mapIoThreePane按参考宽度 1320dp 归一化换算,并配coerceIn边界保护与existingSlot保留既有偏好; - 清洗层
sanitizePaneSizes兜底校验键名与数值合法性; - UI 层
VerticalPaneHandle拖拽写回,双击重置默认; - 测试层以比例输入断言 dp 输出,锁定换算公式。
这套「字符串 pane key + 比例归一化 + 边界夹取 + 清洗兜底」的链路,不只是针对设置页与配置转换,在 DIFF-163~172 等系列变更中同样被复用到 JSON、文本对比、编码解码、Protobuf、加解密、二维码、随手记等所有可拖分栏工具,是整个 Compose 版对 Electron 布局资产迁移的通用基础设施。