KMP 鸿蒙自由窗口实战:一份 Kotlin 核心库管住断点、夹取与窗口状态恢复
社区引导:欢迎加入 KMP&CMP 鸿蒙社区,一起把鸿蒙的系统能力带给每一个跨端开发者。
KMP/CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP
参考框架:https://atomgit.com/oh-tpc
Kotlin 版本:2.2.21-1.0.0(KMP OpenHarmony 适配版,含 ohosArm64 / ohosX64 目标)
适配仓库地址:https://atomgit.com/oh-tpc/kmp-adaptive
如果你正在把一套 KMP 工程往鸿蒙 PC 上搬,大概率会先卡在同一个地方:手机端那套"按屏幕宽度切布局"的经验,到了自由窗口上突然不够用了。 屏幕宽度是常量,窗口宽度却是用户手里一根可以随时拖动的滑杆。本文记录的就是我们围绕这根滑杆做的一次完整工程实践——把"该切成什么布局、该恢复成多大窗口、这套规则本身对不对"这三类判断,全部收进一份 Kotlin 核心库,让 ArkTS 只做执行。

鸿蒙电脑(2in1)上,一个窗口的宽度可以是 400vp,也可以是 1900vp,中间每一档都能被用户用鼠标拖出来。做 PC 端应用,第一个绕不过去的问题就是:布局到底该在哪一刻切换,切成什么样?
这个问题在手机时代几乎不存在。手机屏幕就那么宽,sm/md/lg 三档里永远只命中一档,布局在编译期就基本定型了。但到了自由窗口,用户拖动窗口边缘的每一帧,都可能让宽度跨过某个阈值——上一秒还是三栏列表,下一秒就变成单栏。更麻烦的是,同一个应用可能同时开着好几个窗口,每个窗口宽度不同、断点不同,却要共享同一份 UI 代码。如果这些判断散落在各个页面的 if (width > 840) 里,很快就会变成一场灾难:改一个阈值要翻遍全工程,测一个边界要反复启模拟器拖窗口,而且永远说不清"到底哪一档才是对的"。
这份示例工程把这类判断全部收进一份 Kotlin 的 commonMain 纯逻辑库,ArkTS 只负责"执行"——真正调 window API、读 preferences、拼 UI。换句话说,核心库不碰任何系统对象,它的输入就是几个 Double(窗口宽高、屏幕宽高),输出是一段结构稳定的 JSON;至于这段 JSON 怎么变成界面、窗口怎么被 resize,那是 ArkTS 壳的事。这样切分之后,最值钱的一点是:所有"该不该、该多大"的决策,都能在 JVM 上用普通单测跑,不需要设备、不需要模拟器、不需要拖窗口。 核心库回答三件事:
- 当前窗口宽高该切成
sm/md/lg哪一档、要不要双栏、要不要导航栏; - 上次保存的窗口尺寸还值不值得信任、要不要夹取;
- 这套规则自己有没有写错(自检断言,直接在 HAP 里跑)。
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 26.0.0.821(内置 hvigor / ohpm / SDK) |
| 构建 SDK | HarmonyOS 26.0.0(API 26),compatibleSdkVersion / targetSdkVersion 均为 26.0.0 |
| Kotlin | 2.2.21-1.0.0(KMP OpenHarmony 适配版) |
| 构建主机 | Windows,Gradle 8.x + gradlew.bat |
| 实测设备 1 | DevEco PC 形态模拟器(2in1 自由窗口桌面,x86_64) |
| 实测设备 2 | DevEco 手机模拟器 Mate 90 Pro(1280 × 2832,density 3.50,x86_64,127.0.0.1:5555) |
| 工程形态 | shared(纯 Kotlin 核心)+ nativeApp(C 桥共享库)+ ohosApp(ArkTS 壳) |
这个 demo 不是"又一个响应式列表",它刻意把窗口本身当成一等公民:UI 上实时显示窗口 vp / px、屏幕工作区、density、当前断点、窗口模式,底部还有一条"能自己验证自己"的自检结果。之所以把这些指标全部摊在界面上,是因为调试自由窗口时最怕的就是"看不见输入"——你以为是 800vp,实际回调给的是 799.6vp,断点就卡在边界上;你以为屏幕工作区是整屏,实际被任务栏吃掉了一截。把这些数字实时亮出来,很多"玄学 bug"当场就能定位。下面先看效果,再拆代码。
1. 痛点:自由窗口把"响应式布局"变成实时状态机
手机端的响应式布局是静态的:屏幕宽度是常量,sm/md/lg 一辈子只命中一种。PC 自由窗口把它变成了随鼠标拖拽连续变化的输入,于是三个新问题同时冒出来:
问题一:布局切换的输入变了。 设备类型(phone / tablet / 2in1)已经不能决定布局了——一台 2in1 上,用户把窗口拖窄到 500vp 时,它就应该是单栏手机形态,而不是"平板布局硬塞进小窗口"。所以判定输入必须是 windowSizeChange 回调里的 vp 宽度,而不是 deviceInfo.deviceType。
问题二:窗口尺寸需要跨进程记忆。 用户把窗口拖成 1100 × 700、调好自己的分栏比例、关掉应用,下次打开期待"还是那个样子"。但保存值到下个进程可能已经失效:换了分辨率、接了外接屏、系统 DPI 变了、甚至用户在更小的屏上打开——直接 resize(1100, 700) 会出现"窗口比屏幕还大"的荒谬状态。
问题三:窗口特效 API 有代际差异。 老教程里满屏都是 setWindowMode(WindowMode.WINDOW_MODE_FULLSCREEN),而在 API 26 的 SDK 里 WindowMode 枚举和 setWindowMode 已经被移除,取而代之的是 maximize() / restore() / getWindowStatus()。照抄旧代码,编译期直接报 Cannot find name 'WindowMode'。
这三个问题的共同点:它们都是"该不该、该多大"的判断,而不是"怎么调 API"的动作。 判断写在 ArkTS 里,就绑死在鸿蒙端,且离开设备无法测试(因为和窗口对象纠缠在一起)。所以边界划在这里:
- Kotlin 核心库:纯函数,输入 vp 数字,输出方案 JSON,JVM 上可单测;
- C 桥:
PcwPlan/PcwRestore/PcwChecks三个@CName导出,字符串进、JSON 字符串出; - ArkTS 壳:监听窗口尺寸 → 调桥 → 按 JSON 渲染;执行
resize/maximize/preferences。
2. 效果展示
2.1 PC 形态:多实例、拖拽、断点实时切换

这张图里有三个关键信息:
- 多实例:
launchType设为multiton,点「再开一个实例」通过startAbility拉起同 Ability 的第二个窗口,两个窗口各自维护尺寸状态; - 断点取实时值:右上角 pill 显示
sm/md/lg,随窗口宽度变化; - 底部指标面板是"运行时事实":窗口 vp、窗口 px、屏幕工作区 vp、density、断点、模式六个格子,全部由 KMP/ArkTS 实时计算。
2.2 PC 形态:最大化后双栏

窗口最大化后宽度跨过 1000vp 且高度足够,layoutPlan 里 twoPane 变 true,界面从"单列列表"变成"列表 + 详情"。注意这里双栏的条件不是单纯 width >= 840,而是 宽度 ≥ 1000 且高度 ≥ 500——因为一个 1400 × 400 的扁窗口如果强行双栏,详情区只剩 400 高,体验比单栏还差。这条规则正是核心库里最好写、也是最值得写进单测的那类判断。
2.3 PC 形态:保存窗口状态
点「保存状态」把 {widthVp, heightVp, paneRatio, mode, navExpanded, savedAtMs} 写进 preferences,同时把 JSON 回显到详情区,方便肉眼核对。下次启动时这串 JSON 会被送给 PcwRestore 做夹取,再决定实际 resize 的像素值。回显的 JSON 就落在上一张图底部那条 已保存 {widthVp:1200,...} 里——这是排查"到底存了什么"最省事的入口。
2.4 手机形态:同一份代码,退化为单栏

同一个 HAP 装在 Mate 90 Pro 上,windowSizeChange 报上来的是 360vp 左右,layoutPlan 返回 sm:不显示导航栏、不分栏,列表占满宽度。这就是"把断点建在窗口尺寸上而不是设备类型上"的直接收益——一份 UI,两端形态自动对齐。
2.5 手机形态:只变宽度,布局跟着变

底部指标用 Flex(wrap) 布局,窄屏时自然折行;这是"底部面板高度不够导致文字被裁一半"的第一次教训换来的改法,详见第 5 节踩坑 3。
3. 分层架构:谁该做什么
kmp-ohos-adaptive-window/
├── shared/ 纯 Kotlin,commonMain 无任何平台依赖
│ ├── LayoutPlan.kt 断点枚举 + layoutPlan() 纯函数
│ ├── WindowState.kt SavedWindowState / WindowRestore.restore() / runChecks()
│ ├── Json.kt 极简 JSON 读写(不引三方库,减小 .so 体积)
│ └── commonTest/ JVM 单元测试
├── nativeApp/ KMP → C ABI 共享库
│ ├── ohosArm64Main/ @CName 导出 PcwPlan / PcwRestore / PcwChecks
│ ├── ohosX64Main/ 同一份源码再编一份 x86_64(模拟器用)
│ └── build.gradle.kts prepareOhos / prepareOhosX64 两个拷贝任务
└── ohosApp/ ArkTS 壳
├── entry/src/main/cpp/ NAPI 包装 → 调 .so
└── entry/src/main/ets/
├── window/WindowHub.ets 桥的 TS 声明 + JSON 解析
└── pages/Index.ets 窗口监听、恢复、保存、UI
三层职责非常干脆:
| 层 | 负责 | 不负责 |
|---|---|---|
shared | 断点判定、夹取策略、比例校正、自检 | 任何 window / display / 文件 API |
nativeApp | 把 Kotlin 函数变 C ABI,字符串进出 | 业务判断 |
ohosApp | 监听尺寸、调桥、渲染、调系统 API 落地 | 任何"该多大/该不该"的决策 |
为什么必须双 ABI?因为 DevEco 的 PC 与手机模拟器都是 x86_64,真机是 arm64。只编 arm64,模拟器安装后一启动就崩(找不到 .so 符号);只编 x86_64,真机装不上。工程里用两个 Gradle 任务分别产出并拷进 HAP 工程:
// nativeApp/build.gradle.kts
val prepareOhos by tasks.registering(Copy::class) {
dependsOn("linkDebugSharedOhosArm64")
from(layout.buildDirectory.dir("bin/ohosArm64/debugShared")) {
include("libohos_pcwindow.so"); into("libs/arm64-v8a")
}
from(layout.buildDirectory.dir("bin/ohosArm64/debugShared")) {
include("libohos_pcwindow_api.h"); into("src/main/cpp/include")
}
into(rootProject.layout.projectDirectory.dir("ohosApp/entry"))
}
val prepareOhosX64 by tasks.registering(Copy::class) {
dependsOn("linkDebugSharedOhosX64")
from(layout.buildDirectory.dir("bin/ohosX64/debugShared")) {
include("libohos_pcwindow.so"); into("libs/x86_64")
}
into(rootProject.layout.projectDirectory.dir("ohosApp/entry"))
}
一条命令把两种 ABI 的库都准备好:
gradlew.bat :shared:jvmTest :nativeApp:prepareOhos :nativeApp:prepareOhosX64
4. 核心代码分析
4.1 断点引擎:三个数字,决定一整页布局
// shared/src/commonMain/kotlin/com/ohos/pcwindow/LayoutPlan.kt
public enum class WindowSizeClass(public val label: String) {
COMPACT("sm"),
MEDIUM("md"),
EXPANDED("lg");
public companion object {
public const val MEDIUM_MIN_VP: Double = 600.0
public const val EXPANDED_MIN_VP: Double = 840.0
public fun of(widthVp: Double): WindowSizeClass = when {
widthVp < MEDIUM_MIN_VP -> COMPACT
widthVp < EXPANDED_MIN_VP -> MEDIUM
else -> EXPANDED
}
}
}
断点值刻意和 ArkUI 的推荐值对齐(600 / 840 vp),这样以后就算把 UI 换成 GridRow 的响应式栅格,判定结果也一致,不会出现"KMP 说 lg、GridRow 说 md"的错位。
真正的布局决策在 layoutPlan():
public fun layoutPlan(widthVp: Double, heightVp: Double): LayoutPlan {
val safeWidth = if (widthVp.isFinite() && widthVp > 0) widthVp else 0.0
val safeHeight = if (heightVp.isFinite() && heightVp > 0) heightVp else 0.0
val sizeClass = WindowSizeClass.of(safeWidth)
return when (sizeClass) {
WindowSizeClass.COMPACT -> LayoutPlan(sizeClass.label, safeWidth, safeHeight,
useNavRail = false, twoPane = false, gridColumns = 1, listMaxWidthVp = safeWidth)
WindowSizeClass.MEDIUM -> LayoutPlan(sizeClass.label, safeWidth, safeHeight,
useNavRail = true, twoPane = false, gridColumns = 2, listMaxWidthVp = safeWidth)
WindowSizeClass.EXPANDED -> LayoutPlan(sizeClass.label, safeWidth, safeHeight,
useNavRail = true,
twoPane = safeWidth >= 1000.0 && safeHeight >= 500.0,
gridColumns = 3,
listMaxWidthVp = 480.0)
}
}
三个细节值得说明:
safeWidth兜底:窗口第一次上报尺寸可能是0或NaN(后面踩坑 1 专门讲),不兜底的话断点会算出sm、分栏全塌;- 双栏是复合条件:宽度 ≥ 1000 且 高度 ≥ 500,避免"扁窗口双栏"这种反人类布局;
listMaxWidthVp = 480:大屏下列表不无限拉宽,留白给详情区——这条在Index.ets里通过width(${listMaxWidthVp}vp)直接落到样式上。
LayoutPlan 自带 toJson(),字段顺序稳定,ArkTS 侧解析时不用关心可选字段。
4.2 状态模型与夹取:保存值不可全信
public data class SavedWindowState(
val widthVp: Double,
val heightVp: Double,
val paneRatio: Double,
val mode: WindowMode, // floating / fullscreen / maximize
val navExpanded: Boolean,
val savedAtMs: Long,
)
fromJson() 对每个字段逐项回退默认值(宽 1200、高 800、比例 0.4),所以即使 preferences 里存的是半截脏数据,也不会抛异常。
恢复策略在 WindowRestore.restore(),规则分三档:
public object WindowRestore {
public const val MIN_WIDTH_VP: Double = 320.0
public const val MIN_HEIGHT_VP: Double = 240.0
public const val STALE_RATIO: Double = 2.5
public fun restore(saved: SavedWindowState?, screenWidthVp: Double, screenHeightVp: Double): RestoredWindowState {
val state = saved ?: SavedWindowState.DEFAULT
// 1) 全屏/最大化不需要矩形,只做安全夹取,防止下次切回悬浮时越界
if (state.mode != WindowMode.FLOATING) {
return RestoredWindowState(
widthVp = state.widthVp.coerceIn(MIN_WIDTH_VP, screenWidthVp),
heightVp = state.heightVp.coerceIn(MIN_HEIGHT_VP, screenHeightVp),
paneRatio = state.paneRatio.coerceIn(0.2, 0.8),
mode = state.mode, navExpanded = state.navExpanded,
clamped = false, reason = "mode=${state.mode.name.lowercase()} 无需恢复矩形",
)
}
// 2) 保存值 >> 当前屏幕(换屏/降 DPI):判过期,回退默认尺寸
// 3) 轻微越界:夹到屏幕工作区内
...
}
}
第 2 档和第 3 档的区别是这篇文章里最容易被忽略的一个设计:
| 情况 | 保存 6000 × 4000,屏幕 1920 × 1040 | 保存 2000 × 900,屏幕 1920 × 1040 |
|---|---|---|
| 处理方式 | 判"过期",回退默认 1200 × 800 | 夹取:宽 1920(超屏)、高 900(未超屏,保留) |
| 理由 | 差 2.5 倍说明环境已变,硬夹会得到一个铺满屏的巨型窗口 | 只是越界一点点,用户明显就想占满屏幕宽度 |
STALE_RATIO = 2.5 这个魔数不是拍脑袋:显示器升级通常不会超过 2.5 倍宽度(1920 → 5120 是 2.67 倍,已经属于"环境变了"),而普通的缩放/换小屏都在 2.5 倍以内。
宽高是各自独立判断的——高 900 没超屏 1040,就不该被改成 1040。这条断言我一开始就写错了(见踩坑 4),正是自检把它揪出来的。
4.3 自检:把断言塞进 HAP 里跑
核心库有一份 runChecks(),检查断点边界、布局组合、夹取三档策略:
public fun runChecks(): List<String> {
val problems = mutableListOf<String>()
// 断点边界
if (WindowSizeClass.of(599.9) != WindowSizeClass.COMPACT) problems.add("599.9 应为 sm")
if (WindowSizeClass.of(600.0) != WindowSizeClass.MEDIUM) problems.add("600 应为 md")
if (WindowSizeClass.of(839.9) != WindowSizeClass.MEDIUM) problems.add("839.9 应为 md")
if (WindowSizeClass.of(840.0) != WindowSizeClass.EXPANDED) problems.add("840 应为 lg")
// 布局方案
if (layoutPlan(400.0, 800.0).twoPane) problems.add("sm 不应双栏")
if (!layoutPlan(1100.0, 800.0).twoPane) problems.add("1100x800 应双栏")
if (layoutPlan(1100.0, 400.0).twoPane) problems.add("高度不足不应双栏")
// 恢复:正常值原样通过 / 过期回退默认 / 略超屏夹取 / 全屏保留
...
return problems
}

结果通过 PcwChecks 桥到 ArkTS,UI 右上角显示「● 自检通过」或「● 自检 N 项失败」。这样做的价值在演示场景特别明显:你不需要连电脑、不需要跑 gradlew test,装上 HAP 就能知道打进包里的 Kotlin 逻辑是不是正确的版本——尤其当 .so 是手动拷进工程的时候,"装错架构/装错版本"是高频事故。
4.4 C 桥:字符串进、JSON 出
// nativeApp/src/ohosArm64Main/kotlin/com/ohos/pcwindow/example/NativeBridge.kt
private fun textBuffer(text: String): CPointer<ByteVar> {
val bytes = text.encodeToByteArray()
val buffer = nativeHeap.allocArray<ByteVar>(bytes.size + 1)
bytes.forEachIndexed { index, byte -> buffer[index] = byte }
buffer[bytes.size] = 0
return buffer
}
private inline fun response(block: () -> String): CPointer<ByteVar> = try {
textBuffer(block())
} catch (error: Throwable) {
textBuffer("{\"error\":\"${(error.message ?: "Native error").replace("\"", "'")}\"}")
}
@CName("PcwPlan")
public fun planNative(widthVp: Double, heightVp: Double): CPointer<ByteVar> = response {
layoutPlan(widthVp, heightVp).toJson()
}
三个约定支撑了整套桥的健壮性:
- 一切走 JSON 字符串:ArkTS 侧不用为每个字段写一遍 NAPI 类型映射,字段增删只改两端解析;
- 异常在 C 边界内消化:
response {}把 Kotlin 异常转成{"error": "..."},绝不让异常穿过 FFI 边界(那会直接 abort 进程); - 谁分配谁释放:字符串用
nativeHeap分配,ArkTS 用完必须调PcwFree,否则每次拖窗口都泄漏一小段内存。
连同链接参数一起看:
ohosArm64 {
binaries.sharedLib {
baseName = "ohos_pcwindow"
linkerOpts("--entry=0", "--version-script=${project.file("src/ohosArm64Main/linker/shared-library.map")}")
linkerOpts("-lace_napi.z", "-lhilog_ndk.z")
}
}
--entry=0 关掉可执行入口,--version-script 只导出白名单符号(PcwPlan/PcwRestore/PcwChecks/PcwFree),-lace_napi.z 提供 NAPI 运行时——这三行缺一行,dlopen 就会失败。
4.5 ArkTS 侧:窗口 API 的代际差异
打开 SDK 的 @ohos.window.d.ts 会发现 WindowMode 枚举已经不在,改成了 WindowStatusType + 三个方法:
| 旧写法(API ≤ 14 常见教程) | API 26 实际可用 |
|---|---|
win.setWindowMode(window.WindowMode.WINDOW_MODE_FULLSCREEN) | win.maximize() / win.restore() |
win.getWindowMode() | win.getWindowStatus() |
display.getRect() | display.getDefaultDisplaySync().getAvailableArea()(Promise) |
所以 Index.ets 里的模式切换变成:
/** 最大化 / 悬浮切换(API 26 已移除 setWindowMode,用 maximize/restore)。 */
private toggleMode(): void {
if (this.mainWindow === null) return;
const goingMaximize: boolean = this.windowMode !== 'fullscreen';
const action: Promise<void> = goingMaximize ? this.mainWindow.maximize() : this.mainWindow.restore();
action.then(() => {
this.windowMode = goingMaximize ? 'fullscreen' : 'floating';
this.log(goingMaximize ? '已最大化' : '已还原为悬浮窗口');
}).catch((error: BusinessError) => {
this.log(`模式切换失败(${error.code})`);
});
}
尺寸监听的写法没什么变化,但要注意单位换算:回调给的是 px,而断点判定和布局必须用 vp,densityPixels 就是两者之间的桥:
private registerSizeChange(win: window.Window): void {
this.sizeCallback = (size: window.Size) => {
this.widthVp = size.width / this.density;
this.heightVp = size.height / this.density;
this.layoutPlan = plan(this.widthVp, this.heightVp); // 调 KMP
};
win.on('windowSizeChange', this.sizeCallback);
...
}
aboutToDisappear() 里必须 win.off('windowSizeChange', this.sizeCallback),否则窗口对象活着、页面已销毁,回调会打到一个失效的 ArkTS 实例上。
4.6 持久化与恢复时序
恢复流程的顺序很讲究,错一步就会拿到 0:
window.getLastWindow(this.context()).then((win: window.Window) => {
this.mainWindow = win;
this.registerSizeChange(win); // 1. 先注册监听,拿到当前矩形
display.getDefaultDisplaySync().getAvailableArea() // 2. 再拿屏幕工作区
.then((rect: display.Rect) => {
this.screenWidthVp = rect.width / this.density;
this.screenHeightVp = rect.height / this.density;
this.restoreFromPreferences(win); // 3. 最后才恢复(需要屏幕尺寸做夹取)
});
});
必须"先有屏幕尺寸,才能夹取"。getAvailableArea() 拿的是工作区(已排除任务栏/停靠栏),而不是整屏——用整屏高度去夹取,窗口底部会被任务栏盖住 40~60px,用户能感知到"最大值也不对"。
保存则简单得多,preferences.getPreferencesSync + putSync + flush():
private saveState(): void {
const payload: SavedWindowPayload = {
widthVp: Math.round(this.widthVp), heightVp: Math.round(this.heightVp),
paneRatio: Math.round(this.paneRatio * 100) / 100,
mode: this.windowMode, navExpanded: this.navExpanded,
savedAtMs: new Date().getTime(),
};
const json: string = JSON.stringify(payload);
const prefs = this.loadPrefs();
prefs.putSync(KEY_SAVED, json);
prefs.flush(); // 少了它,进程被杀就丢数据
this.savedJson = json;
}
5. 踩坑与边界条件
这一节全是实测踩出来的,按"症状 → 原因 → 修法"记录。
坑 1:窗口尺寸一直显示 0 × 0。
首次渲染时 getWindowProperties().windowRect 可能还是 0,windowSizeChange 也没那么快触发;display.getAvailableArea() 在部分设备/模拟器上还会直接 reject(我们就遇到了 1300002)。结果 UI 上窗口 vp / px / 屏幕 vp 三格全是 0,resize() 也跟着失败。修法是在根容器上加一层渲染层兜底:
.onAreaChange((oldArea: Area, newArea: Area) => {
const w: number = Number(newArea.width);
const h: number = Number(newArea.height);
if (w > 0 && h > 0) {
this.widthVp = w; this.heightVp = h;
this.layoutPlan = plan(w, h);
this.screenWidthVp = Math.max(this.screenWidthVp, w);
this.screenHeightVp = Math.max(this.screenHeightVp, h);
}
})
onAreaChange 给的是组件实际渲染尺寸(vp),比窗口属性可靠得多,作为兜底最合适。
坑 2:resize() 返回 1300002。
resize / moveWindowTo 只在悬浮态可用,最大化/全屏状态下调用会返回错误码(我们抓到的是 1300002,日志里显示"悬浮态才允许 resize")。所以恢复流程要判断 mode:全屏/最大化时只记录矩形,不去 resize。
坑 3:底部面板的文字被裁掉一半。
第一版把按钮、指标、日志全部平铺在一个没有高度约束的 Column 里,外层被挤压后最后一行只剩半个字。改成"固定高度 + 可换行 + 可滚动"三件套:指标用 Flex(wrap) 自动折行,日志放进固定高 52vp 的 Scroll,整个面板用 Stack(alignContent: Bottom) 悬浮在内容之上,内容区预留 padding({ bottom: 210 }) 让列表不被盖住。
坑 4:自检报"1 项失败",而且是我自己写错的断言。
夹取用例存的是 2000 × 900、屏幕 1920 × 1040,我最初断言 heightVp == 1040——但 900 根本没超屏,正确答案就是 900。JVM 单测里已修正过同样的断言,runChecks() 里漏改,于是 HAP 里一直亮红灯。这就是自检的价值:它抓的是"断言本身写错了"这类最难自查的问题。
坑 5:AppScope 缺图标直接导致 IDE 编译失败(00303038)。
app.json5 里的 icon 是必填字段,但资源只在 entry/src/main/resources/base/media 有 app_icon.svg,AppScope 层没有 → schema 校验报 Schema validate failed, at file: AppScope/app.json5。跨模块引用资源是不允许的,必须在 AppScope/resources/base/media/ 里也放一份同名资源。
坑 6:hvigor 报 00302013 “The root node is not yet available”。
工程里出现了两份 hvigor 实例(一份在工程 node_modules/@ohos/,一份是 IDE 自带的),IDE 的插件检测到双实例就拒绝构建。CLI 构建与 IDE 构建二选一:用 IDE 时清掉工程内的副本,用 CLI 时再补回来。
坑 7:部署 HAP 超时 00404040 / 卡在 “Waiting for emulator online”。
两个 Emulator.exe 进程同时抢 127.0.0.1:5555,hdc 连接被互相踢下线。杀干净后重启单个实例即可。另外同 bundleName 的旧包(签名材料不同)会让安装挂住,先 hdc uninstall 再装。
坑 8:aa start 报 10106102 “device screen is locked”。
模拟器锁屏状态下无法自动启动应用,需要先 power-shell wakeup 唤醒再启动。CI/脚本化部署时这一条最好写进流程。
6. 结论与可直接复用的建议
把这次的经验压缩成几条可以直接抄走的结论:
- 断点判定输入必须是窗口 vp 宽度,不是设备类型;判定结果要包含"是否双栏/是否导航栏",而不是只有一个
sm/md/lg字样; - 双栏条件要复合宽高,宽度 ≥ 1000 且高度 ≥ 500,扁窗口强行双栏体验最差;
- 窗口恢复必须夹取,且区分"夹取"与"过期":差 2.5 倍以内夹边界,超过就回退默认;宽高独立判断,不要用同一套逻辑硬套;
- 执行
resize前先看窗口模式,最大化/全屏状态下调resize只会得到错误码; - 尺寸监听要"三条腿":
windowSizeChange(主)+getWindowProperties()(初始值)+onAreaChange(兜底),任何一条单独用都会在某个时刻给你 0; - 核心逻辑放
commonMain,用自检把断言打进 HAP——.so手动拷贝的工程里,"装错版本"是真实存在的事故。 - 别照抄旧教程的
setWindowMode,API 26 用maximize()/restore()/getWindowStatus()。
最后,这套结构的最大好处不是"少写代码",而是判断可以脱离设备被验证。窗口拖到 600vp 时导航栏该不该出现、保存的 2000 × 900 该不该夹到 1040——这些问题的答案在 JVM 上一次跑 12 个断言就能确认,不需要反复启模拟器、拖窗口、看 UI。对 PC 形态这种"输入连续变化"的场景,这种反馈速度的差别,比代码优雅重要得多。
工程结构速查
| 文件 | 作用 |
|---|---|
shared/.../LayoutPlan.kt | 断点枚举 + layoutPlan() |
shared/.../WindowState.kt | SavedWindowState / WindowRestore.restore() / runChecks() |
nativeApp/.../NativeBridge.kt | @CName 导出三个桥函数 |
ohosApp/.../window/WindowHub.ets | 桥的 TS 声明 + JSON 解析 |
ohosApp/.../pages/Index.ets | 尺寸监听、恢复、保存、UI |
常用命令
# 单测 + 双 ABI 共享库
gradlew.bat :shared:jvmTest :nativeApp:prepareOhos :nativeApp:prepareOhosX64
# 构建签名 HAP
node node_modules/@ohos/hvigor/bin/hvigor.js assembleHap --mode module -p product=default --no-daemon
# 安装 & 启动(模拟器)
hdc install -r entry-default-signed.hap
hdc shell power-shell wakeup
hdc shell aa start -b com.example.hm_webview_demo -a EntryAbility
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)