本文记录 compose-collapsing-toolbar 接入 OpenHarmony 的完整过程，覆盖纯 Compose UI 库的内核提取、折叠状态机逐条移植、ohosArm64 / ohosX64 目标、Kotlin/Native 动态库、C ABI/N-API 桥接、ArkUI 真机页面、HAP 构建和真机验收。

compose-collapsing-toolbar 是 Jetpack Compose 上的 CollapsingToolbarLayout 等价物：CollapsingToolbarScaffold 把 toolbar 高度钳制在 [minHeight, maxHeight]（由子项最小 / 最大高度决定），body 通过嵌套滚动与 toolbar 分摊滚动手势，toolbar 子项以 pin() 钉住、road() 双锚点插值移动、parallax(ratio) 视差三种模式摆放，progress 驱动 Compose 重组联动 UI。本次适配与 KStore 的"真编译整库"路线（社区 Maven 上有完整 HarmonyOS kotlinx 制品线）恰好是镜像场景：这个库一行 kotlinx 依赖都没有，全部源码 import 的是 androidx.compose，后者永远不会出现在 ohos 制品线上——因此走的是社区早期已过审的零依赖内核提取路线（qrose / WheelPickerCompose / Flippable / swipe 同路）：把 UI 下面的折叠算术（高度钳制、进度、亚像素累计器、三种 ScrollStrategy 的滚动分布、road / parallax / pin 摆放公式）移植为零依赖纯 Kotlin 内核，编译成 OpenHarmony 动态库；被提取的不是算法库，而是一台交互状态机，ArkUI 页面逐帧驱动它完成验收。

项目地址： AtomGit/oh-tpc/compose-collapsing-toolbar.git

上游仓库： onebone/compose-collapsing-toolbar

开发工具： 华为云码道

环境安装： 环境安装指南

一、背景

1.1 为什么做 OpenHarmony 平台 KMP/CMP 适配

compose-collapsing-toolbar 为 Compose 应用提供"详情页大图 toolbar 折叠成小标题栏"这一件事的完整答案：rememberCollapsingToolbarScaffoldState() 一行拿状态，scrollStrategy 三选一定义滚动分摊顺序，toolbar 子项用 Modifier.pin() / road() / parallax() 声明摆放语义，state.toolbarState.progress 让字号、透明度随折叠进度插值重组，expand() / collapse() 补间到端点。上游（me.onebone:toolbar-compose 2.3.5）是纯 Android 库：lib 模块 8 个 Kotlin 文件全部站在 androidx.compose 上（Layout、ParentDataModifier、nestedScroll、rememberSaveable），连 KMP 结构都没有。OpenHarmony 应用同样需要这套折叠语义，但上游构建（AGP 7.3.1 / Kotlin 1.7.20 / Compose Compiler 1.3.2）不会生成 OpenHarmony 变体。

如果只在 ArkTS 里手写一个折叠页头，页面可以滚动，却无法证明上游那台调过无数次的折叠状态机在 OpenHarmony ARM64 设备上完成编译、链接和执行——而那台状态机里藏着上游最值钱的东西：钳制的先后顺序、亚像素增量的累计与截断、三种策略下"谁先吃滚动量"的分布顺序、锚点按当前高度解析的 road 插值。适配需要同时验证内核数学、Native 动态库、C ABI、N-API、ArkUI 页面和 HAP 交付链路。

障碍具体问题
目标缺失必须增加 ohosArm64() / ohosX64() 才能生成 OpenHarmony KLIB。
工具链不一致上游 AGP 7.3.1 / Kotlin 1.7.20 与鸿蒙工具链无法共存于一个 Gradle 构建，根构建必须整体替换。
依赖矩阵全库唯一依赖 androidx.compose，社区 Maven（eazytec）上不存在也不会出现其 ohos 制品——"真编译整库"路线在此前提判死。
语言边界不同ArkTS 不能直接持有 Kotlin 对象，需要 C ABI、C++ N-API 和 JSON。
交互语义跨不了桥嵌套滚动的 pre/post 分发、fling 决策、补间动画都是逐帧概念，C ABI 只能同步一来一回。
交付链路复杂.so、CMake、N-API、HAP、签名和 hdc 都要单独验收。

因此，本项目把边界放在：折叠算术的内核提取与逐条移植、根构建替换（cmp_qrose 模式）和 C ABI/N-API 桥接层。UI 原样留在 composeMain 隔离区等待社区 CMP 工具链对齐，ArkTS 只负责手势、动画时钟、渲染与调用 Native。

1.2 库提供的能力

Demo 提供一场真实的折叠会话，对应桥接的全部入口：

  • 测量回报（layout）：toolbar 子项的 min / max 高度进内核，触发与上游测量阶段完全相同的钳制副作用（先 min 后 max、初始 Int.MAX_VALUE 被拉到展开高度）；
  • 逐帧滚动（scroll）：手势每帧的 dy 走 pre 分布，body 消费后余量走 post，返回 consumed / height / offset / progress；
  • fling 决策（fling）：松手速度进内核，按策略与阶段返回 settle 目标（expand / collapse / none）与 body 剩余速度；
  • 补间动画（anim）：expand() / collapse() 的 ~200ms 补间每帧经 dispatchRawDelta 落高度，与上游 AnimationState.animateTo + scrollBy 同路径；
  • 子项摆放（place）：pin / road / parallax 三种模式在当前 progress 下的坐标由内核计算，ArkTS 只做渲染；
  • 版本握手（info）：返回 fork 版本号，来自真实 Native 调用而非静态文字。

响应包含：

字段作用
ok操作是否成功，失败时 error 带原文。
height / min / max当前高度与钳制边界（读数行的数据来源）。
offsetbody 偏移（EnterAlways 系把 toolbar 推出屏幕的量）。
progress折叠进度 0…1（联动 UI 的插值源）。
consumed本帧被脚手架吃掉的滚动量，余量归 body。
target / targetHeight / bodyfling 的 settle 决策与 body 剩余速度。

上游 UI 层能力（rememberSaveable 状态恢复、作用域 DSL、deprecated 的 AppBarContainer / ToolbarWithFabScaffold）属于 Compose 专有语义，隔离在 composeMain 不进内核；内核数学全部有 17 项 jvmTest 交叉验证用例钉死，证明 ohos .so 里执行的折叠逻辑没有漂移。

1.3 实现适配

维度要求
代码复用折叠算术从上游 UI 逐条提取移植（每条规则 KDoc 标注上游文件与行号），Compose UI 原样隔离进 lib/src/composeMain/，不删不改。
平台目标根构建直接声明 ohosArm64 + ohosX64，保留 jvm 作交叉验证，库模块出 KLIB，example/nativeApp 出双 ABI 动态库。
构建隔离根构建替换为极简 ohos 构建（cmp_qrose 模式）；上游 Android 演示 app/ 留盘不进构建。
桥接稳定使用 1 个 C ABI 和 UTF-8 JSON，不传递 Kotlin 对象地址；异常永远不跨 FFI。
依赖纪律内核零第三方依赖（连 kotlinx 都不碰），commonMain 一行依赖坐标都不需要。
UI 完整四 Tab 覆盖全部桥接入口：三种策略、parallax / road / pin、enabled 开关、expand / collapse 补间、实时引擎读数。
仓库规范项目说明、文章、效果图和源码链接统一使用 AtomGit。

本项目的 ArkUI 页面不是 Compose Multiplatform UI 实现。compose-collapsing-toolbar 本身就是 UI 库，UI 层进不了 ohos 是这次适配的起点而不是缺陷；ArkTS Demo 复刻的是上游 MainActivity 与 ParallaxActivity 两个官方演示，骨架数字全部来自内核。

二、实现路线图

第 1 阶段：项目初始化     ── 盘点模块与依赖边界、判定制品线（结论：没有）、确定交付物
第 2 阶段：工具链钉版     ── 根构建替换、eazytec Maven 置前、Kotlin 2.2.21-1.0.0 + Gradle 8.14.1
第 3 阶段：内核提取与移植 ── 折叠状态机逐条搬运、jvmTest 交叉验证（含上游 androidTest 场景）
第 4 阶段：桥协议建模     ── 九 op 扁平 JSON 契约、符号约定、错误通道
第 5 阶段：原生桥接       ── @CName C ABI、C++ N-API、参数校验和内存释放
第 6 阶段：ArkUI 宿主     ── 手写嵌套滚动管线、四 Tab Demo、HAP、签名、真机运行和效果图

三、逐步实现过程

第 1 阶段：项目初始化

1.1 工程边界
lib/                                  上游库模块（改造为纯 KMP：jvm + ohosArm64 + ohosX64）
lib/src/commonMain/                   新增：折叠内核三文件（引擎 + 摆放 + 测量）
lib/src/jvmTest/                      新增：17 项交叉验证
lib/src/composeMain/                  上游 Compose 源码 8 文件 + Manifest + 上下测试，隔离不进构建
example/nativeApp/                    Kotlin/Native 动态库（Bridge + MiniJson）
example/harmonyApp/                   DevEco Stage、CMake N-API 和 ArkTS 页面
README.OpenHarmony.md / _CN.md        鸿蒙适配说明（中英双份）
README.upstream.md                    上游原文保存
app/                                  上游 Android 演示，留盘不进 settings
img/                                  上游动图（enter-always 等），留盘

构建拓扑走 cmp_qrose 模式（根构建即 ohos 构建）：settings.gradle.kts 只 include :lib 与 :example:nativeApp，rootProject.name = "ohos_collapsing_toolbar"。上游的 AGP classpath、buildscript 块随根构建替换整体剥离——本 fork 不发 Maven Central。

1.2 工具链矩阵
项目配置
Kotlin MultiplatformHarmonyOS Kotlin 2.2.21-1.0.0（eazytec Maven）
JDK21（org.gradle.java.home 指向 Temurin 21）
OpenHarmony 目标ohosArm64 + ohosX64（jvm 保留作交叉验证）
Gradle8.14.1（wrapper 替换；2.2.21 旧线必须降 8.x）
依赖commonMain 零依赖（无 kotlinx、无 androidx）
DevEco product5.1.0(18) 兼容
DevEco Studio5.1.0 Release
ABIarm64-v8a + x86_64
Bundleorg.terminator.ohos.collapsingtoolbar
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21.0.12.101-hotspot"
java -version
1.3 源码依赖度盘点
上游文件行数依赖形态处置
CollapsingToolbar.kt387androidx.compose UI + 动画 + 状态隔离 composeMain；状态机数学提取进内核
CollapsingToolbarScaffold.kt201Layout / nestedScroll / rememberSaveable隔离；测量与摆放公式提取
ScrollStrategy.kt240NestedScrollConnection隔离；三策略分布数学逐分支提取
AppBarContainer.kt / ToolbarWithFabScaffold.kt / FabPlacement.kt / FabPosition.kt / Annotations.kt—deprecated 兼容层 / 注解隔离，不入内核

expect / actual 声明全库为零——上游是纯 Android 库，没有平台源码集。这决定了内核提取的唯一工作是"把数学从 Compose 声明里剥出来"，不需要补任何 actual。

1.4 页面边界
标题区          COMPOSE-COLLAPSING-TOOLBAR · OPENHARMONY / 版本握手行（fork 与 Kotlin 版本）
Tab 切换        ExitUntilCollapsed / EnterAlways / Parallax / Engine
脚手架区        toolbar 层（pin 背景 + road 标题或 parallax 头图，clip 随内核高度）+ body 列表层
开关区          Enable collapse/expand（Parallax Tab，对应上游 enabled 参数）
控制区          expand() / collapse() / Reset（Engine Tab，~200ms 补间）
读数行          h / min / max / offsetY / progress / bodyScroll 实时刷新（内核状态直读）
错误行          桥错误通道原文（⚠ 前缀，理论不该出现）

页面启动时先调 op:info 做握手，四个 Tab 各持一个引擎实例（id 1–4）。

第 2 阶段：工具链钉版

2.1 制品线检查（本适配的路线判定）

KStore 适配的第一步是查 eazytec Maven 上有没有 kotlinx 的 ohos 制品（结论是有，走真编译整库）。本项目做同一场检查，结论相反：compose-collapsing-toolbar 的依赖表里没有任何 kotlinx 坐标，全部重量压在 androidx.compose.* 上——后者是 Jetpack 体系，社区 Maven 不会也不该出现它的 ohos 变体。两条推论：其一，"真编译整库"路线在此判死；其二，正因为零依赖，内核提取后的 commonMain 连一条依赖坐标都不用改写，不存在 KStore 那种"版本主体逐字对齐"的选型工作——这是所有已适配 CMP 库里依赖面最小的一个。

2.2 工具链钉版（2.2.21 旧线，Gradle 必须降 8.14.1）

内核零依赖，工具链选择只需对齐社区已过审先例：qrose / WheelPickerCompose / Flippable / swipe 全部钉 HarmonyOS Kotlin 2.2.21-1.0.0，该线只支持 Gradle 8.x，wrapper 从上游 7.5.1 替换为 8.14.1。KStore 的 2.4.20 新线（Gradle 9.x）在这里没有收益——两条工具链线的经验不能互相套用。

settings.gradle.kts 把 eazytec 仓库写在最前：

pluginManagement {
    repositories {
        maven("https://maven.eazytec-cloud.com/nexus/repository/maven-public/")
        maven("https://maven.eazytec-cloud.com/nexus/content/groups/harmonyos")
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

rootProject.name = "ohos_collapsing_toolbar"

include(":lib")
include(":example:nativeApp")
2.3 改造库模块

lib/build.gradle.kts 收敛为纯 KMP 模块：

plugins {
    alias(libs.plugins.kotlin.multiplatform)
}

kotlin {
    applyDefaultHierarchyTemplate()
    jvmToolchain(21)

    jvm()            // 交叉验证用
    ohosArm64()
    ohosX64()

    sourceSets {
        commonMain.dependencies {}

        jvmTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

上游源码 lib/src/main/java/** 整体挪进 lib/src/composeMain/kotlin/**（AndroidManifest.xml、androidTest、test 一并挪入 composeMain/ 留档）。composeMain 不是注册源集，任何目标都不编译它；KMP 的 jvm() 目标默认源集是 src/jvmMain，src/main/java（Android 约定路径）不会被动进编译，但显式挪进隔离区让"哪部分在构建里"一目了然。实测：

.\gradlew.bat :lib:compileKotlinJvm :lib:compileKotlinOhosArm64 :lib:compileKotlinOhosX64   # BUILD SUCCESSFUL
2.4 测试任务的处置

根构建全局禁用 ohos 测试任务（交叉验证统一在 JVM 跑）：

subprojects {
    tasks.matching { it.name.contains("Ohos", ignoreCase = true) && it.name.contains("Test") }
        .configureEach { enabled = false }
}

上游 androidTest 是 Compose 仪器测试（留在隔离区），ohos 侧只承担编译与链接；内核正确性由新写的 jvmTest 承担（第 3.4 节）。

第 3 阶段：内核提取与移植（技术难点）

3.1 内核三文件
新文件移植自内容
CollapsingToolbarEngine.ktCollapsingToolbar.kt:57-186 + ScrollStrategy.kt 全部状态钳制、progress、dispatchRawDelta 与亚像素累计、三策略 pre/post 分布、fling 决策
ToolbarPlacement.ktCollapsingToolbar.kt:256-295 + Alignment 语义偏置对齐模型（九预置）、pin / road / parallax 摆放公式
ScaffoldMeasure.ktCollapsingToolbarScaffold.kt:122-181body maxHeight 约束、body / toolbar 摆放点
3.2 状态机数学：必须逐字节对齐的四条

钳制顺序（CollapsingToolbar.kt:71-94）：minHeight setter 赋值后 if (height < value) height = value；maxHeight setter 是 if (value < height) height = value。测量回报必须先 min 后 max（上游 measure 顺序），初始 height = Int.MAX_VALUE 由 max 拉到展开高度。

亚像素累计器（CollapsingToolbar.kt:108-124）：

fun dispatchRawDelta(value: Float): Float {
    val consume = if (value < 0) max(minHeight.toFloat() - height, value)
                  else min(maxHeight.toFloat() - height, value)
    val current = consume + deferredConsumption
    val currentInt = current.toInt()          // 向零截断
    if (abs(current) > 0f) {
        height += currentInt
        deferredConsumption = current - currentInt
    }
    return consume
}

-0.6 单独一轮什么都不动，两轮才落 1px——这是上游防抖的隐藏细节，测试里用 −0.6×4 步逐轮钉死（100→100→99→99→98）。同样的机制在脚手架 offset 上还有一份（ScrollDelegate）。

三策略分布（ScrollStrategy.kt:80-239）：

策略阶段dy<0（折叠）dy>0（展开）
EnterAlwayspretoolbar 吃到 min → 余量进 offset，钳 offset ≥ −height（当前高度）offset 先回 0 → 余量 toolbar 吃到 max
EnterAlwaysCollapsedpre同上offset 先回 0（高度不动）
EnterAlwaysCollapsedpost不处理全部给 toolbar（body 已到顶）
ExitUntilCollapsedpre全部给 toolbar不处理
ExitUntilCollapsedpost不处理全部给 toolbar

fling 净决策：上游把速度交给 Android 样条 FlingBehavior 衰减到端点；内核不模拟样条，改为回答"谁接管、走向哪个 bound、body 剩多少"——EnterAlways 在 pre 吃正向速度、EnterAlwaysCollapsed 在 post 吃 body 用剩的正向速度、ExitUntilCollapsed 在 pre 吃负向 / post 吃正向，且只在还有余地（canMove）时接管，否则速度全额还给 body。

3.3 摆放公式：锚点按当前高度解析
PlacementMode.ROAD -> {
    val collapsed = whenCollapsed.align(childW, childH, toolbarW, toolbarHeight)
    val expanded  = whenExpanded.align(childW, childH, toolbarW, toolbarHeight)
    IntOffset2D(
        collapsed.x + ((expanded.x - collapsed.x) * progress).roundToInt(),
        collapsed.y + ((expanded.y - collapsed.y) * progress).roundToInt(),
    )
}
PlacementMode.PARALLAX -> IntOffset2D(0, -((maxHeight - minHeight) * (1 - progress) * ratio).roundToInt())

两个易错点：parallax 的取整在取负之内（−62.5 → −63，不是 −62）；road 的两个锚点都按 IntSize(maxWidth, height)（当前高度，CollapsingToolbar.kt:271-281）解析，锚点本身随容器收缩而移动——这是 road 运动感的来源，也是移植时最容易想当然的地方（见 8.1 踩坑第 4 条）。align 复刻 androidx 公式：((space − size) / 2 · (1 + bias)).roundToInt()，偏置 −1/0/1 对应 start/center/end。

3.4 交叉验证：连移植者的误解都能拦

lib/src/jvmTest/.../CollapsingToolbarEngineTest.kt，17 项用例，期望值全部从上游源码推导：

断言域用例数钉住什么
钳制与进度4上游 androidTest testCollapse 场景（layout 后 progress1、height300；累计 −250 上滑后 height==50、`
dispatchRawDelta2端点停摆（−400 只吃 −250）、亚像素 −0.6×4 步逐轮高度
EnterAlways 分布2折叠 toolbar→offset、offset 只能到 −(height)、+200 实吃 120
EnterAlwaysCollapsed2折叠高度→offset、pre 展开只还 offset、post 展开进高度
ExitUntilCollapsed1pre 只吃折叠、post 只吃展开
fling 决策23 策略 × pre/post × 方向的 target 矩阵、bound 处速度全额还 body
摆放公式3parallax 三点（含取整方向）、road 三点（50 高容器内 CenterStart 是 (0,5)）、pin 与对齐解析
脚手架测量1bodyMax 三策略 + 越界 coerce、body / toolbar 摆放点

一轮真实返工：初版 road 测试按"展开态容器 300 高"算锚点，两条用例当场红——翻回上游 271-281 行确认对齐空间是当前高度，修的是测试期望而不是内核。交叉验证的价值正在于此：它不仅拦内核漂移，连移植者自己的误解一起拦。

第 4 阶段：桥协议建模

4.1 JSON 契约
me.onebone.toolbar/**（内核：引擎 + 摆放 + 测量，commonMain 编译）
        ↓ 折叠状态机：钳制 / 分布 / 插值
Bridge.kt（@CName × 1，扁平 JSON 进出，id 键引擎注册表）
        ↓ UTF-8 JSON
N-API collapsingToolbarDispatch()
        ↓
ArkUI Index.ets（四 Tab，手写嵌套滚动管线）

请求与响应：

请求 : {"op":"scroll","id":1,"dy":-12.5,"phase":"pre"}
       {"op":"layout","id":1,"min":50,"max":150}
       {"op":"fling","id":1,"velocity":-900,"phase":"pre"}
       {"op":"place","mode":"road","progress":0.5,"cw":220,"ch":56,"tw":360,"th":175,
        "min":50,"max":150,"collapsed":"CenterStart","expanded":"BottomEnd"}
响应 : {"ok":true,"height":137,"offset":0,"progress":0.785,"min":50,"max":150,"consumed":-12.5}
       {"ok":false,"error":"..."}

九个 op：info（握手）/ create / dispose（实例生命周期）/ layout（测量回报）/ scroll（pre|post 分布）/ anim（补间帧直进高度）/ fling（settle 决策）/ place（子项坐标）/ measure（body 约束）。

两个设计约定：符号沿用 Compose（dy > 0 展开、手指下移为正——ArkUI PanGesture 的 offsetY / velocityY 恰好同向，桥上不用翻转）；单位统一 vp（引擎不关心单位，进度与比例无量纲）。

4.2 为什么是每帧一调用

qrose 是"一次调用一图"、WheelPickerCompose 是"一次 snap 一调用"，本库是连续手势库，桥粒度必须到帧：上游嵌套滚动本来就是逐 delta 分发的（onPreScroll 每帧带 available），ArkTS 拿到 consumed 后把余量喂给自己的 body 钳制，再决定是否调 post——与 Compose 的 pre → child → post 顺序一一对应。折叠是 60fps 交互，但桥载荷刻意最小（scroll 一个 op 七个字段，往返微秒级），"扁平、单函数、异常不跨界"的社区契约不变。

4.3 错误通道

每个导出整体 try/catch，Kotlin 异常永远不跨 FFI，非法参数（缺 dy、未知策略、未知对齐名）统一走 {"ok":false,"error":"…"} 通道，ArkTS 侧渲染到 ⚠ 错误行。

第 5 阶段：原生桥接

5.1 三层桥接
ArkTS
  │ JSON string
  ▼
C++ N-API entry（libcollapsingtoolbar_napi.so）
  │ const char*
  ▼
Kotlin/Native C ABI（libohoscollapsingtoolbar.so）
  │ CollapsingToolbarDispatch
  ▼
UTF-8 JSON + DisposeString

直接导出 Kotlin 对象会暴露 ABI 和生命周期问题；只导出整数又会让页面复制折叠语义，所以选择 C ABI + JSON。

5.2 Kotlin/Native 导出函数
@CName("CollapsingToolbarDispatch")
fun collapsingToolbarDispatch(request: String): String   // 九 op 一口进
C ABI 符号ArkTS 方法覆盖内核
CollapsingToolbarDispatchcollapsingToolbarDispatch(req)引擎注册表 + 九 op 全部分发

info op 承担版本握手（返回 fork / Kotlin 版本与 op 清单），真机版本行的数据来源。

5.3 C++ N-API 方法分发
napi_property_descriptor desc[] = {
    {"collapsingToolbarDispatch", nullptr, NapiCollapsingToolbarDispatch, nullptr, nullptr, nullptr,
     static_cast<napi_property_attributes>(napi_default | napi_enumerable), nullptr},
};

每个回调统一三步：napi_typeof 校验必须是 string、OH_LOG_INFO 打字节数、调 KN 函数并包装返回。KN 返回的字符串必须经 libohoscollapsingtoolbar_symbols()->DisposeString 归还 Kotlin 运行时，绝不 free()。libohoscollapsingtoolbar_api.h 按社区已审仓库同款手写（只声明 ExportedSymbols 结构与一个业务符号），不拖整份生成头。

5.4 CMake 和类型声明
add_library(ohoscollapsingtoolbar SHARED IMPORTED)
set_target_properties(ohoscollapsingtoolbar PROPERTIES
  IMPORTED_LOCATION ${KN_SO}
  IMPORTED_NO_SONAME TRUE)

add_library(collapsingtoolbar_napi SHARED napi_init.cpp)
target_link_libraries(collapsingtoolbar_napi PUBLIC
  libace_napi.z.so
  libhilog_ndk.z.so
  ohoscollapsingtoolbar)

OHOS_ARCH 为空或 libohoscollapsingtoolbar.so 缺失直接 FATAL_ERROR（提示先跑 link 任务）；$ORIGIN rpath 加 POST_BUILD 拷贝保证 NAPI so、KN so、libc++ 三件套同目录，dlopen 时互相可见。

export const collapsingToolbarDispatch: (request: string) => string;

第 6 阶段：ArkUI 宿主

6.1 手写嵌套滚动管线（pre → body → post）
private applyDelta(composeDy: number): void {
  const pre = JSON.parse(dispatchRaw({ op: 'scroll', id: this.paneId, dy: composeDy, phase: 'pre' })) as StateRes;
  const remaining: number = composeDy - (pre.consumed ?? 0);        // 余量归 body

  const clamped: number = Math.min(Math.max(this.bodyScroll - remaining, 0), this.bodyMaxScroll());
  const bodyConsumed: number = -(clamped - this.bodyScroll);        // body 实吃（钳制后）
  this.bodyScroll = clamped;
  let leftover: number = remaining - bodyConsumed;

  if (Math.abs(leftover) > 0.01) {                                   // post：EAC / EUC 吃展开余量
    const post = JSON.parse(dispatchRaw({ op: 'scroll', id: this.paneId, dy: leftover, phase: 'post' })) as StateRes;
    this.syncState(post);
  }
  this.syncState(pre);
  this.applyProgressExtras();                                        // road / parallax 坐标 + 字号插值
}

为什么 body 不用原生 List + onScrollFrameBegin：ArkUI 列表在顶边 EdgeEffect.None 时不再派发帧回调，展开 toolbar 的 post 通道会丢事件；手写管线把 pre → body → post 的顺序完整握在手里，与上游嵌套滚动分发严格一致（WheelPickerCompose 手写滚轮的同款取舍）。

6.2 释放、fling 与补间

松手 velocityY 进 op:fling（pre），target 非空则跑 ~200ms ease-out 补间到 targetHeight，每帧经 op:anim（dispatchRawDelta）落高度——与上游 expand() 用 AnimationState.animateTo + scrollBy 的路径同构，钳制与亚像素累计全程参与；target 为空则 body 以 0.92/帧衰减 fling，每帧仍走 applyDelta（嵌套语义连续），衰减殆尽且 body 在顶部仍有余速时补一发 fling(post)（onPostFling 孪生）。Engine Tab 的 expand() / collapse() 按钮直接触发同一条补间路径。

6.3 四 Tab 与上游 Demo 的对应
Tab上游出处要点
ExitUntilCollapsedMainActivity150vp 背景 pin + 50vp 隐形 spacer 定最小高度 + road(CenterStart→BottomEnd) 标题（字号 18+12·progress）
EnterAlways同款 toolbar 换策略toolbar 收到最小后被 offset 推出屏幕，下拉先回 toolbar
ParallaxParallaxActivity50vp spacer + 300vp 头图 parallax(0.5) 且 alpha = progress，EnterAlwaysCollapsed，右下 Floating Button!，顶部 Enable collapse/expand 开关（enabled 参数，关掉后滚动直通 body）
Engineexpand() / collapse() API补间按钮 + 实时读数 + info 握手

每个 Tab 底部都有读数行（h=… min=… max=… offsetY=… progress=… bodyScroll=…），滚动时实时跳动——"数字来自内核"的直接验收面。

6.4 工程结构
example/
├── nativeApp/
│   ├── build.gradle.kts                      双 ABI sharedLib（baseName=ohoscollapsingtoolbar）+ cxxShared + copyKnSo*
│   └── src/ohosMain/kotlin/example/nativeapp/
│       └── Bridge.kt                         @CName + MiniJson + 引擎注册表（扁平 JSON，继承自 cmp_qrose 审核模式）
└── harmonyApp/
    ├── build-profile.json5                   signingConfigs 留空（签名由 DevEco 自动生成回填）
    ├── AppScope/app.json5                    bundleName org.terminator.ohos.collapsingtoolbar、versionName 2.3.5-ohos.1
    └── entry/
        ├── build-profile.json5               externalNativeOptions + abiFilters [arm64-v8a, x86_64]
        ├── libs/{arm64-v8a,x86_64}/          linkDebugShared* 经 copyKnSo* 回填的三件套（gitignore）
        ├── src/main/cpp/CMakeLists.txt       IMPORTED 引入 KN so、$ORIGIN rpath
        ├── src/main/cpp/napi_init.cpp        N-API 导出、参数检查、DisposeString
        ├── src/main/cpp/include/libohoscollapsingtoolbar_api.h
        ├── src/main/cpp/types/libcollapsingtoolbar_napi/{index.d.ts, oh-package.json5}
        └── src/main/ets/pages/Index.ets      ArkUI 四 Tab 验收页面
6.5 构建、签名和安装
.\gradlew.bat :lib:jvmTest                                                        # 17 项交叉验证
.\gradlew.bat :example:nativeApp:linkDebugSharedOhosArm64 :example:nativeApp:linkDebugSharedOhosX64

cd example\harmonyApp
hvigorw assembleHap -p product=default -p buildMode=debug --no-daemon

签名在 DevEco Studio 的 File → Project Structure → Signing Configs 中勾选自动生成，证书写入本机 ~/.ohos/config，不进入仓库（仓库内 build-profile.json5 的 signingConfigs 保持空数组，勾选自动签名后由 IDE 回填带 material 的完整配置）。

hdc list targets -v
hdc -t <设备序列号> install -r \
  entry/build/default/outputs/default/entry-default-signed.hap
hdc -t <设备序列号> shell aa start \
  -a EntryAbility -b org.terminator.ohos.collapsingtoolbar -m entry

四、完整代码对照

4.1 整体架构

me.onebone.toolbar/**（折叠内核，commonMain 新增三文件）
    │ CollapsingToolbarEngine / ToolbarPlacement / ScaffoldMeasure
Bridge.kt + MiniJson
    │ CollapsingToolbarDispatch（九 op）
libcollapsingtoolbar_napi.so
    │ collapsingToolbarDispatch
Index.ets
    │ 手写嵌套滚动管线 + JSON parse + @State 更新
    ▼
ArkUI 真机页面（四 Tab）

4.2 文件清单

文件职责
settings.gradle.kts极简 ohos 构建、eazytec Maven 置前、ohos_collapsing_toolbar、app/ 移出
gradle/libs.versions.tomlKotlin 2.2.21-1.0.0 钉版
build.gradle.kts（根）版本 2.3.5-ohos.1、全局禁用 Ohos*Test* 任务
lib/build.gradle.kts纯 KMP：jvm + ohosArm64 + ohosX64，零依赖
lib/src/commonMain/.../CollapsingToolbarEngine.kt状态钳制 + dispatchRawDelta + 三策略分布 + fling 决策
lib/src/commonMain/.../ToolbarPlacement.kt偏置对齐模型 + pin / road / parallax 公式
lib/src/commonMain/.../ScaffoldMeasure.ktbody 约束 + body / toolbar 摆放点
lib/src/jvmTest/.../CollapsingToolbarEngineTest.kt17 项交叉验证（含上游 androidTest 场景）
example/nativeApp/build.gradle.kts双 ABI sharedLib、cxxShared 定位 libc++、copyKnSo* 回填
nativeApp/.../Bridge.kt1 个 C ABI、九 op 分发、MiniJson、错误通道
harmonyApp/.../cpp/napi_init.cppN-API 导出、参数检查、DisposeString
harmonyApp/.../cpp/CMakeLists.txtIMPORTED 引入 KN so、$ORIGIN rpath、POST_BUILD 三件套
harmonyApp/.../ets/pages/Index.etsArkUI 四 Tab 验收页面（嵌套滚动管线）
README.OpenHarmony_CN.md鸿蒙适配主文档（18 节）

4.3 关键 API 对照

层次API作用
引擎layout(min, max)测量回报，含钳制副作用与先后顺序（上游 measure policy）
引擎preScroll(dy) / postScroll(dy)三策略的滚动分布（上游三个 NestedScrollConnection）
引擎dispatchRawDelta(v)高度直进 + 亚像素累计（上游 ScrollableState lambda）
引擎fling(v, phase)settle 决策 + body 剩余速度（上游 onPre/PostFling 净语义）
引擎progress(height−min)/(max−min)，联动 UI 插值源
摆放ToolbarPlacement.place(mode, …)pin / road / parallax 坐标（上游 placement pass）
测量ScaffoldMeasure.bodyMaxHeight(…)body 约束（ExitUntilCollapsed 扣 toolbarMin）
NativeCollapsingToolbarDispatchC ABI JSON 导出
N-APIcollapsingToolbarDispatch(req)向 ArkTS 暴露能力
ArkTSapplyDelta(dy)pre → body → post 管线并刷新 UI

4.4 ArkTS 与 Kotlin 的边界

const pre = JSON.parse(collapsingToolbarDispatch(JSON.stringify({
  op: 'scroll', id: 1, dy: -12, phase: 'pre',
}))) as StateRes;
toolbarStack.height(pre.height);                       // 折叠中的高度
bodyStack.position({ y: pre.height + pre.offset });    // body 摆放点
titleText.fontSize(18 + 12 * pre.progress);            // progress 联动

fun preScroll(dy: Float): Float = when (strategy) {
    StrategyKind.ENTER_ALWAYS -> enterAlwaysPreScroll(dy)      // toolbar→offset→body
    StrategyKind.ENTER_ALWAYS_COLLAPSED -> enterAlwaysCollapsedPreScroll(dy)
    StrategyKind.EXIT_UNTIL_COLLAPSED -> exitUntilCollapsedPreScroll(dy)
}

两者之间只传输扁平 JSON 字符串，不传输 Kotlin 对象或未校验的动态结构。

五、关键决策说明

决策 1：内核提取而不是真编译整库

KStore 走真编译整库的前提是 eazytec 上有它依赖的完整 kotlinx ohos 制品线；本库的依赖表里只有 androidx.compose，这个前提永远不成立。但"没有制品"不等于"没有价值"——上游值钱的部分（钳制顺序、亚像素累计、三策略分布、锚点插值）是纯数学，与渲染无关，提取成本约 500 行零依赖 Kotlin。与 qrose / WheelPickerCompose / Flippable / swipe 构成社区内核路线的连续先例。

决策 2：工具链钉 2.2.21 旧线，Gradle 降 8.14.1

内核零依赖，不存在"由依赖制品线反推 Kotlin 版本"的约束，工具链直接对齐社区已过审的内核路线先例（qrose / WheelPickerCompose 全部是 2.2.21-1.0.0 + Gradle 8.14.1）。KStore 的 2.4.20 线（Gradle 9.x）是为 kotlinx 新制品线服务的，在这里没有收益——两条工具链线的经验不能互相套用。

决策 3：fling 用净决策而不是样条移植

上游样条衰减是 Android FlingBehavior 的平台实现细节。内核回答"谁接管、走向哪个 bound、body 剩多少"即可语义等价：ArkTS 拿到 target 后跑补间，每帧仍经 dispatchRawDelta 落高度，钳制与累计器全程参与——settle 的路径与上游 expand() 完全同构，只是时钟从 Android 动画框架换成了 ArkTS setInterval。

决策 4：每帧 JSON 桥 + 读数行

连续手势库的桥粒度必须到帧，但契约纪律（扁平、单函数、异常不跨界、DisposeString 归还）与 qrose 完全一致；每个 Tab 底部的读数行让 h / min / max / offsetY / progress 在真机上肉眼可对拍第 3.2 节的分布表，验收不依赖 hilog。

决策 5：签名材料不进仓

build-profile.json5 的 signingConfigs 留空数组（条目缺 material 字段会被 hvigor schema 拒绝），DevEco 勾自动签名回填本机；上游 Android 演示 app/ 与 Compose 隔离区留盘不进构建，作为对照与未来回接的底稿。

六、测试与验证

6.1 测试环境

本次验证使用 Windows（x64）、JDK 21（Temurin）、DevEco Studio 5.1.0 Release、OpenHarmony 命令行工具（hvigor / hdc）与鸿蒙真机（arm64）。

6.2 JVM 交叉验证

.\gradlew.bat :lib:jvmTest

17 项用例全部通过（分域统计见 3.4 节表格）。与 KStore"上游原测试文件零改动"不同，本库上游只有 Compose 仪器测试（进不了 JVM），因此交叉验证是新写的——但其中最关键的一组直接移植自上游 androidTest 的 testCollapse 场景（300/50 双子项 → 折叠到 50），断言原文照抄（|progress| < 0.01）。

6.3 HAP 验证

:lib:compileKotlinOhosArm64 / OhosX64: BUILD SUCCESSFUL
linkDebugSharedOhosArm64 / linkDebugSharedOhosX64: BUILD SUCCESSFUL
llvm-nm -D: CollapsingToolbarDispatch / libohoscollapsingtoolbar_symbols 均为全局 T 符号
BuildNativeWithNinja: finished（双 ABI 编出 libcollapsingtoolbar_napi.so）
CompileArkTS: finished
PackageHap: finished
BUILD SUCCESSFUL
install bundle successfully
start ability successfully

entry-default-unsigned.hap 约 6.8 MB，内含双 ABI 各三件套（libcollapsingtoolbar_napi.so / libohoscollapsingtoolbar.so / libc++_shared.so）；HAP 内 strip 后 KN so arm64 约 1.9MB、x86_64 约 1.9MB（debugShared 未 strip 时分别约 3.69MB / 3.40MB，含 Kotlin/Native 运行时——本库没有 kotlinx 依赖，比 KStore 的 so 显著更小）。

6.4 功能用例

  1. 启动后标题下方版本行出现 fork 2.3.5-ohos.1 · Kotlin 2.2.21-1.0.0 · ops: info/create/…（来自真实 Native 调用，非静态文字）；
  2. ExitUntilCollapsed Tab 上滑：toolbar 从 150 收到 50 并钉住，road 标题从 CenterStart 走向 BottomStart 侧锚点、字号从 30 收到 18，读数行 progress 从 1.00 走到 0.00；
  3. EnterAlways Tab 继续上滑：toolbar 被 offset 推出屏幕（读数 offsetY 走负），body 顶到状态栏下；下拉时 offset 先归零、toolbar 再展开；
  4. Parallax Tab：头图以 0.5 系数视差且透明度随 progress 渐隐；关掉 Enable collapse/expand 后滚动直通列表、toolbar 冻结（enabled 参数语义）；
  5. 松手 fling：按策略与方向回弹到端点（ExitUntilCollapsed 上滑松手直接收到底），回弹是补间而非瞬移；
  6. Engine Tab 点 expand() / collapse()：~200ms 缓动补间，读数行连续走字；Reset 归位 body 与 toolbar；
  7. 每帧滚动读数行实时刷新，h/min/max 与声明的子项高度一致（50/150、50/300）；
  8. 桥错误通道：理论不该出现，出现时 ⚠ 行显示原文、页面不崩溃。

6.5 验证结论

折叠内核、Native 动态库、C ABI、N-API、ArkUI 页面和 HAP 已完成链路验证。应用在鸿蒙真机上成功安装并进入前台，四 Tab 手势与读数构成完整验收面（见下节效果图）。

七、运行效果

7.1 真机截图

在这里插入图片描述

7.2 命令速查

git clone https://atomgit.com/oh-tpc/compose-collapsing-toolbar.git
cd compose-collapsing-toolbar
export JAVA_HOME="/path/to/jdk-21"
./gradlew :lib:compileKotlinOhosArm64 :lib:compileKotlinOhosX64     # klib
./gradlew :lib:jvmTest                                             # 17 项交叉验证
./gradlew :example:nativeApp:linkDebugSharedOhosArm64 :example:nativeApp:linkDebugSharedOhosX64
cd example/harmonyApp
hvigorw assembleHap -p product=default -p buildMode=debug --no-daemon
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b org.terminator.ohos.collapsingtoolbar -m entry
hdc shell hilog | grep CollapsingToolbar

八、遗留问题与改进方向

8.1 踩坑复盘

  1. 只改 ArkTS 页面不算 KMP/CMP 适配，必须让折叠状态机真正编译成 ohosArm64 / ohosX64 动态库，并由页面逐帧调用；
  2. settings.gradle.kts 里 eazytec 双仓必须排在 pluginManagement 与 dependencyResolutionManagement 最前，否则配置期直接 Unresolved reference: ohosArm64；
  3. 制品线检查的结论可以是"没有"：androidx.compose 不存在 ohos 制品是路线判定的输入而不是障碍——零依赖内核路线照样成立，且 commonMain 连依赖坐标都不用改写；
  4. road 锚点按当前高度解析：初版按展开态容器算锚点，JVM 交叉验证当场打脸；上游 271-281 行的对齐空间是 IntSize(maxWidth, height)，锚点随容器收缩移动——修测试期望，内核本来就对；
  5. ArkUI PanGesture 的 offsetY / velocityY 与 Compose 的 dy / velocity 同向（手指下移为正 = 展开），桥上不用做符号翻转；但 body 滚动方向相反（dy<0 时 bodyScroll 增长），余量换算时别混；
  6. ArkUI 原生列表顶边 EdgeEffect.None 时不再派发帧回调，嵌套滚动的 post 通道会丢事件——body 必须手写钳制管线，不能依赖 onScrollFrameBegin；
  7. hvigorw assembleHap 的 PackageHap 需要 java：spawn java ENOENT 时把 JAVA_HOME 指到 Temurin 21 再跑；
  8. 根构建的 /build/ 与 .idea/* 是根锚定模式，盖不住嵌套目录——DevEco 打开工程后生成的 example/harmonyApp/.idea/ 与 example/nativeApp/build/ 要单独追加 gitignore，否则混进提交；
  9. build-profile.json5 的 signingConfigs 条目缺 material 字段会被 hvigor schema 拒绝（报 00303038 must have required property 'material'）——仓库内留空数组且 product 不引用签名，勾选自动签名后由 IDE 回填完整配置；
  10. HAP 缺当前 ABI 的 so 会报安装失败 9568347，abiFilters 必须双 ABI，每个 ABI 三件套缺一不可；
  11. KN 返回字符串必须 DisposeString 归还运行时，N-API 层不能 free()；
  12. 签名材料由 DevEco 自动写入 build-profile.json5，提交前用 git update-index --skip-worktree 保护，证书绝不进入 AtomGit。

8.2 已知问题

  • road 子项尺寸由声明常量给出（TITLE_W × TITLE_H 的定尺寸容器），不是动态文本测量——上游测量真实 child，ArkTS 侧视觉等价；
  • RTL / layoutDirection 未移植（上游 placeRelative 在 LTR 下与 place 等价，Demo 只跑 LTR），偏置模型已保留，接 RTL 时在 ArkTS 侧翻 x 即可；
  • deprecated 的 AppBarContainer / ToolbarWithFabScaffold / FabPlacement / FabPosition 未入内核（上游迁移兼容层，行为与主 API 重复），隔离在 composeMain；
  • rememberSaveable 的状态恢复语义不适用：HAP 侧无跨进程恢复场景，引擎随组件生命周期 create / dispose；
  • body 列表非虚拟化（Demo 60 行 Text），业务接入应换 List 或复用手写管线；
  • EnterAlways 折叠钳制用当前高度（-height - offsetY）是上游行为不是 bug：toolbar 收缩后 offset 上限跟着变小；
  • HAP 安装必须使用与 bundle name org.terminator.ohos.collapsingtoolbar 匹配的签名。

8.3 未来优化方向

  • 补真机（x86_64）与其他设备 ABI 的验收矩阵和自动化截图脚本；
  • 评估 .har 形态发布，让 ArkTS 工程直接依赖而不是走 so 三件套；
  • 在 CI 中加入 ohos 编译、ELF 符号检查和 HAP 构建；
  • EnterAlwaysCollapsed 的 onPostFling 触发细节增加专项真机用例（当前依赖帧管线 + fling(post) 双通道）；
  • 社区 CMP 鸿蒙线与上游 Compose 版本对齐后，把 composeMain 重新挂回编译、内核退化为共享状态层。

九、总结

9.1 核心难点回顾

上游 compose-collapsing-toolbar（100% androidx.compose）
    → 制品线检查（结论：没有）→ 判定零依赖内核路线
    → 工具链对齐 Kotlin 2.2.21-1.0.0（Gradle 8.14.1 降版）
    → 根构建替换（cmp_qrose 模式）+ Compose 源码隔离 composeMain
    → 折叠状态机逐条提取（钳制顺序 / 亚像素累计 / 三策略分布 / 锚点插值）
    → ohosArm64 / ohosX64 KLIB + 双 ABI 动态库
    → C ABI（@CName × 1，九 op）+ 每帧扁平 JSON
    → C++ N-API（DisposeString 纪律）
    → ArkTS 手写嵌套滚动管线（pre → body → post）
    → ArkUI 真机四 Tab 验收（三策略 / parallax / road / 补间 / 读数）

9.2 封装层次

  • 内核层：CollapsingToolbarEngine（钳制、进度、累计器、分布、fling 决策）、ToolbarPlacement（对齐模型与三摆放公式）、ScaffoldMeasure（body 约束与摆放点）；
  • Native 层：生成双 ABI 动态库并通过 1 个 C ABI 输出 JSON；
  • N-API 层：完成参数检查、字符串转换和 Native 内存释放；
  • ArkTS 层：手写嵌套滚动管线、手势与 fling 时钟、补间驱动、页面状态与读数；
  • DevEco 层：完成 CMake、HAP、签名、安装和真机运行。

9.3 三条经验

  1. 制品线检查的结论可以是"没有"，这同样是路线判定的输入：纯 Compose UI 库没有 kotlinx 依赖可换线，正确答案是提取 UI 下面的数学——零依赖内核的 commonMain 连一条依赖坐标都不用改，适配面反而最小；社区内核路线（qrose / WheelPickerCompose / Flippable / swipe）因此构成与 KStore 真编译路线互补的另一半地图；
  2. 交互状态机的移植必须钉"顺序"而不只是"公式"：钳制的先后（min 先 max 后）、分布的先后（pre 里 toolbar→offset）、取整的先后（parallax 取负之内、锚点按当前高度解析）——JVM 交叉验证连移植者自己的误解都能拦下来（本轮就拦了 road 锚点一处）；
  3. 连续手势库的桥粒度到帧，契约纪律不变：一帧一个 scroll op、七个字段、往返微秒级，"扁平 JSON、单函数、异常不跨界、DisposeString 归还"与一图一回的 qrose 完全一致——变的是粒度，不变的是边界。

9.4 适配成果

当前适配已完成：

  • compose-collapsing-toolbar 2.3.5 折叠内核的双 ABI Kotlin/Native 编译（上游 Compose UI 零删改隔离进 composeMain，内核三文件每条规则标注上游出处）；
  • 1 个 C ABI 符号和 C++ N-API 包装层（llvm-nm 验证全局 T 符号）；
  • DevEco Stage ArkUI 四 Tab 验收页面（三策略、parallax / road / pin、enabled 开关、expand / collapse 补间、实时引擎读数）；
  • 17 项 JVM 交叉验证全绿（含上游 androidTest 场景移植）+ HAP 构建（双 ABI 六件套 so，约 6.8MB）、签名、设备安装和真机验证；
  • AtomGit 项目文档、OpenHarmony README（中英双份）和本地效果图。

适配过程 FAQ

以下问题来自 ohosArm64 目标接入、NAPI 桥接、HAP 构建与真机验收的实际流程，按出现频率排序。

Q1：DevEco Studio Sync 失败或 ohpm 依赖下载超时，怎么处理？

  • 确认 DevEco Studio 版本与工程 build-profile.json5 的 compatibleSdkVersion 一致；
  • 在 File > Settings > Build, Execution, Deployment > Ohpm 配置可用的 ohpm 仓库镜像或代理；
  • 删除 oh_modules、oh-package-lock.json5 与 .hvigor 缓存后重新 Sync；
  • 公司网络需要代理时，同时给 ohpm 与 hvigor 配置 http.proxy。

Q2：CMake 报 Missing .../libxxx.so 或找不到 Kotlin/Native 动态库？

  • 先在 example 目录执行 ./gradlew :nativeApp:linkDebugSharedOhosArm64（模拟器用 linkDebugSharedOhosX64）；
  • 确认 libxxx.so 与 libc++_shared.so 已复制到 ohos/entry/libs/<abi>/；
  • 检查 entry/build-profile.json5 的 abiFilters 与设备 ABI 是否一致（真机 arm64-v8a，模拟器 x86_64）；
  • 清理 entry/.cxx 与 entry/build 后重试。

Q3：ArkTS 报 Cannot find module 'libxxx_napi.so' 或调用返回 undefined？

  • 确认 CMake 的 add_library(<target> SHARED ...) 名称与 import ... from 'libxxx_napi.so' 完全一致；
  • 解包 HAP，确认 libs/<abi>/libxxx_napi.so 已打包；
  • 删除 entry/build、entry/.cxx 与 oh_modules 后重新构建；
  • 检查 module.json5 的 srcEntry 与页面路径是否正确。

Q4：真机安装报 signature verification failed 或 install failed？

  • 在 DevEco Studio 的 Signing Configs 配置证书、Profile 与密码；
  • bundleName 必须与签名 profile 中的 bundle name 一致；
  • 设备需加入 profile 的 deviceIds，调试证书有效期需覆盖当前时间；
  • 用 hdc list targets 确认设备在线，再执行 hdc install -r xxx-signed.hap。

Q5：应用启动白屏、闪退或 NAPI 调用崩溃？

  • 用 hdc hilog | grep -i "napi\|kotlin" 查看原生日志；
  • 确认 libc++_shared.so 与 Kotlin/Native 工具链版本匹配，且 ABI 与设备一致；
  • 检查 C ABI 返回的字符串是否由 Native 侧分配、ArkTS 侧复制后是否调用 XxxFree 释放；
  • 在 DevEco 的 Native 调试配置中附加 lldb，定位空指针与越界访问。

Q6：Gradle 报 ohosArm64 目标不存在或 Kotlin/Native 编译失败？

  • 使用鸿蒙发行版 Kotlin（如 2.2.21-1.0.0），并在 settings.gradle.kts 配置 eazytec 仓库；
  • Gradle 建议 8.x、JDK 21，版本不匹配时先统一工具链；
  • 确认 kotlin { ohosArm64() } 已应用，且 local.properties 的 SDK 路径有效；
  • 清理 ~/.gradle/caches 中对应版本的 Kotlin/Native 缓存后重试。

Q7：HAP 构建报 SDK 版本不匹配或 compatibleSdkVersion 错误？

  • 对齐 DevEco Studio、HarmonyOS SDK 与 build-profile.json5 中的 compatibleSdkVersion；
  • 升级 DevEco Studio 后同步升级 hvigor 与 SDK，避免 modelVersion 与 IDE 不匹配；
  • 命令行构建时设置 DEVECO_SDK_HOME 指向 DevEco 的 sdk 目录。

Q8：命令行 hvigor 构建失败，但 DevEco 里能构建？

  • 使用 DevEco 自带的 node 与 hvigor：
    "$DEVECO/Contents/tools/node/bin/node" "$DEVECO/Contents/tools/hvigor/bin/hvigorw.js" ...；
  • 设置 JAVA_HOME、NODE_HOME、DEVECO_SDK_HOME；
  • 加上 --no-daemon 排除守护进程缓存影响，并清理 entry/build 与 .hvigor。

参考文档

# 开源 # harmonyos # 华为
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙应用：获取前台 UI 界面的应用包名

通过hdc工具执行hdc shell uitestdumpLayout生成当前页面布局的JSON文件，利用DevEco Studio的设备文件浏览器查看位于/data/local/tmp目录下的layout_xxx.json文件，解析type为root节点的attributes字段，可获取当前前台应用的包名（bundleName）、Ability名称（abilityName）及页面路径（PageP

avatar 人工智能6S服务平台

开源鸿蒙平台 CMP 三方库「Dropdown」适配全流程

上游 dropdown(commonMain 全量 Compose 依赖)→ 源码依赖度盘点:枚举纯净 / 工厂绑 Transition / Composable 绑 Material3→ 拆分:枚举下沉 commonMain,工厂与 Composable 隔离 composeMain(零删除)→ 工具链对齐 HarmonyOS Kotlin 2.2.21-1.0.0(Gradle 8.14.1)

avatar 人工智能6S服务平台
cover

【鸿蒙心迹】鸿蒙 PC 应用上架实战：分布式 Markdown 笔记从开发到过审全流程

avatar 人工智能6S服务平台