社区引导:欢迎加入 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 只做执行。

PC 端:桌面同时叠放三个实例,每个窗口按自身宽度独立切换断点

鸿蒙电脑(2in1)上,一个窗口的宽度可以是 400vp,也可以是 1900vp,中间每一档都能被用户用鼠标拖出来。做 PC 端应用,第一个绕不过去的问题就是:布局到底该在哪一刻切换,切成什么样?

这个问题在手机时代几乎不存在。手机屏幕就那么宽,sm/md/lg 三档里永远只命中一档,布局在编译期就基本定型了。但到了自由窗口,用户拖动窗口边缘的每一帧,都可能让宽度跨过某个阈值——上一秒还是三栏列表,下一秒就变成单栏。更麻烦的是,同一个应用可能同时开着好几个窗口,每个窗口宽度不同、断点不同,却要共享同一份 UI 代码。如果这些判断散落在各个页面的 if (width > 840) 里,很快就会变成一场灾难:改一个阈值要翻遍全工程,测一个边界要反复启模拟器拖窗口,而且永远说不清"到底哪一档才是对的"。

这份示例工程把这类判断全部收进一份 Kotlin 的 commonMain 纯逻辑库,ArkTS 只负责"执行"——真正调 window API、读 preferences、拼 UI。换句话说,核心库不碰任何系统对象,它的输入就是几个 Double(窗口宽高、屏幕宽高),输出是一段结构稳定的 JSON;至于这段 JSON 怎么变成界面、窗口怎么被 resize,那是 ArkTS 壳的事。这样切分之后,最值钱的一点是:所有"该不该、该多大"的决策,都能在 JVM 上用普通单测跑,不需要设备、不需要模拟器、不需要拖窗口。 核心库回答三件事:

  1. 当前窗口宽高该切成 sm / md / lg 哪一档、要不要双栏、要不要导航栏;
  2. 上次保存的窗口尺寸还值不值得信任、要不要夹取;
  3. 这套规则自己有没有写错(自检断言,直接在 HAP 里跑)。

0. 环境与实测设备

项版本/型号
DevEco Studio26.0.0.821(内置 hvigor / ohpm / SDK)
构建 SDKHarmonyOS 26.0.0(API 26),compatibleSdkVersion / targetSdkVersion 均为 26.0.0
Kotlin2.2.21-1.0.0(KMP OpenHarmony 适配版)
构建主机Windows,Gradle 8.x + gradlew.bat
实测设备 1DevEco PC 形态模拟器(2in1 自由窗口桌面,x86_64)
实测设备 2DevEco 手机模拟器 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 形态:多实例、拖拽、断点实时切换

PC 端:三个窗口实例叠放,前台 md、后方 lg 各自维护布局,互不干扰

这张图里有三个关键信息:

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

2.2 PC 形态:最大化后双栏

PC 端:最大化后断点升到 lg,左侧列表 + 右侧详情形成双栏,底部回显已保存 JSON 与自检结果

窗口最大化后宽度跨过 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 手机形态:同一份代码,退化为单栏

手机端:断点 sm,无导航栏、单栏列表占满宽度;截图取自修复前版本,底部 0×0 与「自检失败 1 项」正是第 5 节踩坑 1、4 的现场

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

2.5 手机形态:只变宽度,布局跟着变

手机端:窗口模式 pill、自检状态,以及指标面板用 Flex(wrap) 在窄屏下自动折行的效果

底部指标用 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)
  }
}

三个细节值得说明:

  1. safeWidth 兜底:窗口第一次上报尺寸可能是 0 或 NaN(后面踩坑 1 专门讲),不兜底的话断点会算出 sm、分栏全塌;
  2. 双栏是复合条件:宽度 ≥ 1000 且 高度 ≥ 500,避免"扁窗口双栏"这种反人类布局;
  3. 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
}

PC 端:「断点断言与自检结果」页,右侧直接输出 layoutPlan / clampWindow / restore 的全部断言结果

结果通过 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()
}

三个约定支撑了整套桥的健壮性:

  1. 一切走 JSON 字符串:ArkTS 侧不用为每个字段写一遍 NAPI 类型映射,字段增删只改两端解析;
  2. 异常在 C 边界内消化:response {} 把 Kotlin 异常转成 {"error": "..."},绝不让异常穿过 FFI 边界(那会直接 abort 进程);
  3. 谁分配谁释放:字符串用 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. 结论与可直接复用的建议

把这次的经验压缩成几条可以直接抄走的结论:

  1. 断点判定输入必须是窗口 vp 宽度,不是设备类型;判定结果要包含"是否双栏/是否导航栏",而不是只有一个 sm/md/lg 字样;
  2. 双栏条件要复合宽高,宽度 ≥ 1000 且高度 ≥ 500,扁窗口强行双栏体验最差;
  3. 窗口恢复必须夹取,且区分"夹取"与"过期":差 2.5 倍以内夹边界,超过就回退默认;宽高独立判断,不要用同一套逻辑硬套;
  4. 执行 resize 前先看窗口模式,最大化/全屏状态下调 resize 只会得到错误码;
  5. 尺寸监听要"三条腿":windowSizeChange(主)+ getWindowProperties()(初始值)+ onAreaChange(兜底),任何一条单独用都会在某个时刻给你 0;
  6. 核心逻辑放 commonMain,用自检把断言打进 HAP——.so 手动拷贝的工程里,"装错版本"是真实存在的事故。
  7. 别照抄旧教程的 setWindowMode,API 26 用 maximize() / restore() / getWindowStatus()。

最后,这套结构的最大好处不是"少写代码",而是判断可以脱离设备被验证。窗口拖到 600vp 时导航栏该不该出现、保存的 2000 × 900 该不该夹到 1040——这些问题的答案在 JVM 上一次跑 12 个断言就能确认,不需要反复启模拟器、拖窗口、看 UI。对 PC 形态这种"输入连续变化"的场景,这种反馈速度的差别,比代码优雅重要得多。


工程结构速查

文件作用
shared/.../LayoutPlan.kt断点枚举 + layoutPlan()
shared/.../WindowState.ktSavedWindowState / 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
Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐