社区引导:欢迎加入 KMP&CMP 鸿蒙社区,一起把鸿蒙的系统能力带给每一个跨端开发者。

KMP/CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP

提交仓库:https://atomgit.com/oh-tpc/kmp-ohos-frame-atlas

参考框架与社区组织:https://atomgit.com/oh-tpc | https://atomgit.com/CPF-KMP-CMP

0. 环境与实测设备

项版本 / 型号
DevEco Studio26.0.0.851(内置 hvigor / ohpm / SDK,build DS-261.23567.138.36.2600851)
构建 SDKcompatibleSdkVersion 6.0.0(API 20),targetSdkVersion / compileSdkVersion 26.0.0
Kotlin Multiplatform2.2.21-1.2.0(鸿蒙适配版,含 ohosArm64 / ohosX64 目标)
Compose Multiplatform1.9.2-1.2.0(鸿蒙适配版)
Skiko / ohpm 组件0.9.22.2-1.2.0 / @cpf-kmp-cmp/compose 1.9.2-1.2.0
三方库koalaplot-core 0.12.1(上游,MIT)→ 移植版 0.12.1-ohos.1
Gradle / JDK8.9 / 17.0.2(org.gradle.java.home 固定)
实测设备DevEco 手机模拟器,HUAWEI emulator,7.0.0.107(SP8DEVC00E999R4P11),API 26,x86_64,127.0.0.1:5555
示例仓库kmp-ohos-frame-atlas(koalaplot 移植库 + composeApp + example/ohos 宿主)

测量口径先说清楚,否则后面的数字会被误读:本文所有帧耗时来自应用内 androidx.compose.runtime.withFrameNanos 的相邻帧回调间隔,单位是毫秒;它是 Compose 帧时钟给出的时间戳之差,不是 DevEco Profiler 的 GPU 渲染耗时,也不是 hiTraceMeter 的打点区间。统计代码全部在 commonMain 纯 Kotlin 中实现,两份 ABI 共用同一套算法;Gradle 与 hvigor 的构建耗时、产物体积则来自各自的构建日志。测量条件是:同一台模拟器、同一个 1000 卡 LazyColumn、手动持续拖动长列表、每次独立点击「开始采样 / 停止并出报告」,不做多轮取平均,也不跨设备比较。文中凡涉及"改造前后"的对比,都会注明它是代码级可复算数据、构建日志数据还是设备采样数据。

在跨端团队里,「长列表有点卡」几乎是最难推进的一类问题:用户说不出是哪一帧,测试给不出稳定复现路径,开发翻日志只看到几条正常的组合记录。KMP/CMP 鸿蒙工程还多一层——Compose 的组合与重组发生在 Kotlin/Native 动态库里,ArkTS 宿主只负责托管渲染,系统级性能工具给出的时间线很难直接指到某个 Composable;想引一个现成的 Compose 图表库把帧耗时画出来,又会发现它根本没有鸿蒙编译目标。于是「要不要优化」变成主观争论,「优化有没有效果」更无从验证。本文做的事很具体:把 KoalaPlot 移植到鸿蒙双 ABI,在 Kotlin 侧建一套可自检的帧耗时统计,再用 1000 卡长列表把真实数据跑出来。需要提前说明的是,本文不宣称列表渲染性能得到提升,基线列表代码原样保留;下文所有「改造前后」的对比,比较的是归因能力与测量判据,而不是渲染速度。

1. 先看效果:五张截图里藏着一个反直觉现象

先不谈原理。应用叫「掉帧归因实验台」,首屏就三件事:一行自检结果、一个「开始采样」按钮、一份采样报告。

初始状态:自检 20/20 通过,报告数值全为 0,KoalaPlot 标线停在 16.7 ms

第一张图是冷启动后的初始态。绿色文字「帧统计自检 20/20 通过」是移植到鸿蒙 Native 之后最重要的一道保险:分位数、慢帧率、分桶、环形缓冲绕回、CSV 表头等 20 条断言在应用进程里真实跑过,不是桌面 JVM 上的模拟结果。此时还没有任何采样帧,P50 / P95 / P99 都是 0,KoalaPlot 画出的只有一条 16.7 ms 的紫色标线和五个定性区间。这张图同时说明一件事:图表库已经能在鸿蒙 CMP 渲染链路上完成测量、布局与绘制,移植不是"能编译"而是"能出图"。

采样中:30 帧时 P95 34.26 ms,慢帧率 100%,最长帧 34.27 ms

第二张图是点击开始采样、刚滚动到列表顶部时的实时面板:30 帧,P95 34.26 ms,慢帧率 100.0%,最长帧 34.27 ms。下方 1000 张卡片按序号即时构造,文案里的「帧耗时样本」「标签数」都随序号变化——这是刻意保留的基线负载:不给 key、不给 contentType、每次进入组合都重新拼字符串,目的就是让重组开销真实存在。

采样中:630 帧,列表已滚动到卡片 #38 附近,指标仍为 P95 34.26 ms

第三张图是滚动到卡片 #38 到 #44 区间、累计 630 帧时的状态。P95 依旧 34.26 ms,慢帧率依旧 100.0%,最长帧 34.28 ms。这说明前 630 帧里,34 ms 量级的帧不是偶发的一两帧,而是占了足够高的比例,能把 P95 直接顶上去。

第一次报告:1093 帧,P50 17.13 / P95 34.26 / P99 34.27 ms,分布 0/0/857/236/0

第四张图是第一次停止采样后的完整报告:1093 帧,P50 17.13 ms,P95 34.26 ms,P99 34.27 ms,最长帧 34.28 ms,慢帧率 100.0%,连续慢帧段 1;帧耗时分布(<8 / 8–16.7 / 16.7–33.3 / 33.3–50 / >50 ms)是 0 / 0 / 857 / 236 / 0。也就是说 78.4% 的帧落在 16.7–33.3 ms,21.6% 落在 33.3–50 ms,没有一帧低于 8 ms,也没有一帧超过 50 ms。下方移植版 KoalaPlot 的 BulletGraph 里,紫色条形(P95)明显越过了 16.7 ms 标线,压在第二、第三个区间之间。

第二次报告:3164 帧,P50 17.12 / P95 17.14 / P99 34.26 ms,分布 0/0/3083/81/0

第五张图是第二次独立采样、累计 3164 帧后的报告。这里出现了整篇文章最值得停下来看的反直觉现象:采样帧数多了近两倍,P95 却从 34.26 ms 掉到 17.14 ms,P99 仍有 34.26 ms,慢帧率仍然写著 100.0%,而 33.3–50 ms 桶从 236 帧变成 81 帧(占比从 21.6% 降到 2.6%)。BulletGraph 的紫色条形也缩回到 16.7 ms 标线附近。

如果只盯着"慢帧率 100%“和"P95 34 ms”,很容易得出"这个长列表持续严重掉帧"的结论;但把五张图连起来读,会看到三个互相矛盾又互相解释的事实:设备的基础帧间隔大约是 17.1 ms,34 ms 恰好是它的两倍,像丢掉一个 vsync 的形态;100% 的慢帧率不可能全是真实卡顿,更可能是判据本身失真;P99 在两次采样里都稳定在 34.26 ms,说明长尾确实存在,只是占比被采样窗口摊薄了。这正是"掉帧归因"和"看个帧率数字"的区别:前者要能回答"哪些帧是真的慢、慢在哪个阶段、我的阈值是不是错的",后者只会给出一个吓人的百分比。

2. 痛点:跨端长列表的卡顿,难在"没有可归因的数据"

长列表卡顿是移动端最老的问题,但在 KMP/CMP 鸿蒙工程里它有额外的三层困难。

第一层是观测口径缺失。Android 上还有 Choreographer、FrameMetricsAggregator、Perfetto 这些成熟入口,鸿蒙侧也有 DevEco Profiler 和 hiTraceMeter,可它们给出的多是系统级时间线;而 CMP 的组合、重组、Skiko 绘制发生在 Kotlin/Native 侧的动态库里,跨过 ComposeArkUIViewController 这道边界后,光靠 ArkTS 层看不出"这一帧慢是列表项重组慢,还是宿主布局慢"。如果应用自己不记录帧与帧之间的间隔,事后就只能靠"感觉有点卡"来描述问题。

第二层是平均值会骗人。一次 60 秒的滚动里,哪怕有 80 帧各慢了 34 ms,平均帧耗时也只从 17.1 ms 抬到 17.5 ms 左右,看起来"基本没问题";但用户感知到的恰恰是那 80 帧造成的顿挫。优化类文章经常写"优化后平均帧耗时下降多少",这类指标对长尾几乎不敏感。真正该看的是分位数、超过预算的帧数、以及慢帧是否连续成段——这也是本文把 P50 / P95 / P99、五档直方图、连续慢帧段一起端上来的原因。

第三层是工具链与生态缺口。要在界面上把帧耗时分布画出来,最省事的做法是引一个 Compose 图表库;但绝大多数 Compose Multiplatform 三方库只声明了 android、jvm("desktop")、iosArm64、js、wasmJs 目标,没有 ohosArm64 / ohosX64。更麻烦的是版本代际:本文选中的 KoalaPlot v0.12.1 上游用 Kotlin 2.4.10 与 CMP 1.11.1 构建,而鸿蒙适配版停在 Kotlin 2.2.21-1.2.0 / CMP 1.9.2-1.2.0。直接把 Maven 坐标写进依赖,Kotlin/Native 链接阶段面对的是不兼容的 klib 元数据,implementation("io.github.koalaplot:koalaplot-core:0.12.1") 这条路从一开始就走不通。

所以这个选题要解决的不是"加个图表",而是把三件原本分散的事情拧成一条链:把三方图表库真正移植到鸿蒙双 ABI;在 Kotlin 侧建立一套低开销、可自检的帧耗时统计;用一个真实的长列表负载把数据跑出来,并诚实地解释数据里的异常。三者缺一,文章就只剩下截图和口号。

还要强调一点:本文没有对 LazyColumn 做代码级优化,1000 卡基线负载是刻意保留的。因此下文所有"改造前后"对比,比较的是归因工具链与测量判据,不是渲染性能提升;把工具链的改进包装成"列表快了几倍"是不诚实的,也不符合优化类选题要求的测量纪律。真正的列表优化(key、contentType、derivedStateOf、分页预取)需要另一次 A/B 实测,本文在结论里给出可直接照做的方案与判据。

3. 原理:一帧从 ArkTS 走到 Kotlin,再变成一张分布图

先把渲染链路摊开。example/ohos/entry/src/main/ets/pages/Index.ets 在 aboutToAppear 里取到 UIAbilityContext,把 deviceInfo.sdkApiVersion 与 context.filesDir 两个参数交给 nativeApi.createController;napi_init.cpp 校验参数后调用 Kotlin 导出的 MainArkUIViewController;Kotlin 侧 initMainHandler(env) 初始化主线程协程分发,再用 ComposeArkUIViewController(env) { FrameAtlasApp() } 把 Compose 内容托管给 @cpf-kmp-cmp/compose 的 Compose 组件。构建时 CMP 鸿蒙插件会给两个目标注入 fusion-renderer 的链接参数与 Skiko overlay,最终产物是一份 libkn.so(ARM64 与 X64 各一份)和配套的 libkn_api.h。

在这条链路上,withFrameNanos 拿到的是 Compose 帧时钟在每帧回调时给出的纳秒时间戳。它有两个必须写进文章的性质:其一,它来自 Compose 的组合/绘制调度,和系统硬件 vsync 不是同一个时钟,因此 17.12 ms 这个基线不能直接当成"设备刷新率 60Hz";其二,两次回调的差值包含了上一帧的组合、测量、绘制以及等待下一次调度的时间,所以它更适合衡量"用户是否感觉顿了一下",不适合单独归因"是 Kotlin 组合慢还是 Skiko 绘制慢"。要做后者,需要在同一时间轴上叠 hiTraceMeter 或 DevEco Profiler 的区间数据。本文不假装它能替代系统工具,只把它当作跨端应用自己能稳定拿到的帧间隔来源。

统计侧采用线性插值分位数:把采样数组排序后,用 rank = p × (n − 1) 定位,整数部分与小数部分做插值。这样即便样本数不是 100 的整数倍,P95 也不会退化成"第 95 个最大值"这种随样本量跳变的近似。直方图按 8 / 16.7 / 33.3 / 50 ms 切成五档,边界是按 60 Hz 预算的 0.5 倍、1 倍、2 倍、3 倍取的,因此第二档到第三档的跃迁直接对应"丢一帧",第四档以上对应"连续丢两帧以上"。连续慢帧段则只统计"连续两帧都超阈值"的段数,用来区分零星抖动与成片卡顿。

图表侧选 KoalaPlot,是因为它是纯 Compose Multiplatform 实现的图表库,API 面就是 Composable,不依赖 Android View、不依赖平台 Canvas 封装,理论上只要补齐 expect/actual 就能在鸿蒙 CMP 上跑;而且它自带坐标轴、刻度、定性区间与 BulletGraph,正好能把"P95 与 16.7 ms 预算的关系"画成一眼能看懂的图。相比之下,图片加载或分页类库虽然也和长列表性能强相关,但依赖面涉及 ktor、okio 或 androidx paging,移植风险会盖掉本文要讲的归因主线。

4. 三方库移植:为什么必须"源码级",以及改了哪四处

先把不能走捷径的原因说透。Kotlin/Native 的 klib 带有编译器版本元数据,上游用 Kotlin 2.4.10 编译出的 koalaplot-core 产物,在 2.2.21-1.2.0 的鸿蒙工具链里无法链接;CMP 1.11.1 与 1.9.2-1.2.0 之间的 Compose 运行时 ABI 也不能假设兼容。因此本工程采用源码级移植:把上游 tag v0.12.1(commit 993e246b5a5c3d58e97747868ef3c5a24cd8b7c4)的 src/commonMain/kotlin 原样复制到 koalaplot 模块,用鸿蒙工程的插件重新编译。好处是 77 个上游文件一行不改就能参与编译,坏处是必须自己维护一份"上游基线 + 改动清单",这就是 koalaplot/UPSTREAM.json 的作用:记录仓库、tag、commit、MIT 许可、移植版本 0.12.1-ohos.1 以及四条改动,避免几个月后没人说得清这份代码从哪来、改过什么。

四处改动分别是:

序号改动原因
1Gradle 目标从 androidLibrary / iosArm64 / iosSimulatorArm64 / js / jvm("desktop") / wasmJs 换成 ohosArm64() + ohosX64()手机、平板走 ARM64,Windows x86_64 模拟器走 X64,两份 klib 共用 ohosMain
2依赖从上游的 compose.*:1.11.1、kotlinx-coroutines:1.11.0 换成 CMP 鸿蒙插件提供的 compose.foundation/material3/ui/animation 与 1.10.2-0.4.0 协程与 1.9.2-1.2.0 的鸿蒙适配版对齐,避免同包不同版本
3新增 ohosMain 的 Modifier.onGestureInput actual上游只给 Android / iOS / Desktop / JS / Wasm 写了 actual,缺一个平台实现就过不了编译
4去掉 dokka、detekt、ktlint、explicitApi() 与发布用的 convention.publication 插件这些属于上游发布流水线,移植模块只需要编译产物;上游的 public 修饰符原样保留,API 面不变

模块的完整构建脚本如下(为符合征文要求,文中代码块的注释统一改为中文,逻辑与仓库同名文件一致):

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
    `maven-publish`
}

// 上游:KoalaPlot/koalaplot-core v0.12.1(MIT)
// 源码级引入:上游 klib 由 Kotlin 2.4.10 / CMP 1.11.1 编译,鸿蒙工具链无法链接
group = "io.github.koalaplot"
version = "0.12.1-ohos.1"

kotlin {
    // 真机 ARM64 + Windows x86_64 模拟器 X64
    ohosArm64()
    ohosX64()

    sourceSets {
        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
            api(compose.ui)
            api(compose.animation)
            implementation(libs.kotlinx.coroutines.core)
        }
        // 两个 ABI 共享同一份 ohosMain,与社区库模板一致
        val ohosMain by creating {
            dependsOn(commonMain.get())
        }
        getByName("ohosArm64Main").dependsOn(ohosMain)
        getByName("ohosX64Main").dependsOn(ohosMain)
    }
}

publishing {
    publications.withType<MavenPublication>().configureEach {
        pom {
            name.set("Koala Plot Core for HarmonyOS")
            description.set("Koala Plot 0.12.1 source-level port to HarmonyOS (ohosArm64/ohosX64), MIT")
            url.set("https://atomgit.com/oh-tpc/kmp-ohos-frame-atlas")
            licenses {
                license {
                    name.set("MIT")
                    url.set("https://github.com/KoalaPlot/koalaplot-core/blob/main/LICENSE.txt")
                }
            }
            scm { url.set("https://github.com/KoalaPlot/koalaplot-core") }
        }
    }
}

这里有两个容易被忽略的细节。一是 gradle.properties 里写了 kotlin.mpp.applyDefaultHierarchyTemplate=false,所以 ohosMain 不会被自动推导出来,必须显式 by creating 并让两个目标的 Main 源集 dependsOn 它,否则 commonMain 与平台源集之间会断开。二是 api(compose.ui) 与 api(compose.animation) 用 api 而不是 implementation,因为上游的公开签名里直接出现了 Modifier、Offset、IntSize、AnimationSpec 等类型,降级成 implementation 会让消费方在编译期找不到类型。

第三处改动的手势 actual 也值得单独看。上游把这个 expect 按输入设备分成了两类:桌面与 Web 用 onPointerEvent 处理鼠标滚轮,Android 与 iOS 用 pointerInput + detectTransformGestures 处理触摸。鸿蒙的是触摸为主,所以直接复用 androidMain 的实现:

package io.github.koalaplot.core.util

import androidx.compose.animation.SplineBasedFloatDecayAnimationSpec
import androidx.compose.ui.Modifier
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.unit.IntSize
import io.github.koalaplot.core.animation.PanFlingBehavior
import io.github.koalaplot.core.gestures.GestureConfig
import io.github.koalaplot.core.gestures.TransformGesturesHandler
import io.github.koalaplot.core.gestures.TransformGesturesHandlerImpl
import io.github.koalaplot.core.gestures.pan.PanFlingHandlerImpl
import io.github.koalaplot.core.gestures.pan.PanHandlerImpl
import io.github.koalaplot.core.gestures.zoom.LockedRatioZoomHandler
import io.github.koalaplot.core.gestures.zoom.StickyAxisZoomHandler

/** 鸿蒙侧 actual:复用 Android 的触摸手势链路,补齐上游缺失的平台实现。 */
@Suppress("LongParameterList")
internal actual fun Modifier.onGestureInput(
    key1: Any?,
    key2: Any?,
    gestureConfig: GestureConfig,
    onZoomChange: (size: IntSize, centroid: Offset, zoom: ZoomFactor) -> Unit,
    onPanChange: (size: IntSize, pan: Offset) -> Boolean,
): Modifier = this then Modifier.pointerInput(key1, key2, gestureConfig) {
    // 最小触点间距决定双指缩放的判定阈值
    val minTouchesDistance = viewConfiguration.minimumTouchTargetSize.width.toPx()

    val gesturesHandler: TransformGesturesHandler = TransformGesturesHandlerImpl(
        panHandler = PanHandlerImpl(),
        panFlingHandler = PanFlingHandlerImpl(
            panFlingBehavior = PanFlingBehavior(
                animationSpec = SplineBasedFloatDecayAnimationSpec(density = this),
            ),
        ),
        zoomHandler = if (gestureConfig.independentZoomEnabled) {
            StickyAxisZoomHandler(minTouchesDistance)
        } else {
            LockedRatioZoomHandler()
        },
    )
    gesturesHandler.detectTransformGestures(
        scope = this,
        gestureConfig = gestureConfig,
        onZoomChange = onZoomChange,
        onPanChange = onPanChange,
    )
}

移植结果不是"改到能编译"就收工::koalaplot:compileKotlinOhosX64 一次通过,77 个上游 commonMain 文件全部参与编译,只有一条上游自带的 BulletGraphItem.kt:394 unchecked cast 警告;随后 linkDebugSharedOhosX64、publishDebugBinariesToHarmonyApp 分别产出 56,967,960 字节的 X64 libkn.so 和 59,384,904 字节的 ARM64 libkn.so,最终 HAP 61,559,097 字节,包内 libs/arm64-v8a/libkn.so 与 libs/x86_64/libkn.so 均在。上游代码与 MIT 许可原文分别留在 koalaplot/README.upstream.md 与 koalaplot/LICENSE.txt,新增鸿蒙桥接与示例代码另用 LICENSE-MIT 声明——这部分是三方库移植最容易被审稿人挑刺的地方,务必留痕。

5. 采样链路:让测量本身尽量不污染测量结果

很多掉帧监控之所以失真,是因为监控代码自己每帧触发一次重组:写一次 mutableStateOf,整个页面跟着重组一次,测出来的"卡顿"里混着监控器的开销。本工程的做法是把"每帧记录"和"定期发布"拆开,完整实现只有 40 行:

package com.ohos.frameatlas.trace

import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.State
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.withFrameNanos

/**
 * 用 Compose 帧时钟采样相邻帧间隔,每 publishEvery 帧才发布一次聚合结果,
 * 让采样代码自身不逐帧重组页面。
 */
@Composable
fun rememberFrameStats(trace: FrameTrace, enabled: Boolean, publishEvery: Int = 30): State<FrameStats> {
    // 状态只在组合期创建一次,后续刷新只改 value
    val stats = remember { mutableStateOf(FrameMath.summarize(doubleArrayOf())) }
    LaunchedEffect(trace, enabled) {
        if (!enabled) return@LaunchedEffect
        var previous = 0L
        var sincePublish = 0
        try {
            while (true) {
                // 挂起到下一帧,拿到 Compose 帧时钟的纳秒时间戳
                val now = withFrameNanos { it }
                if (previous != 0L) {
                    // 相邻帧间隔转毫秒;首帧没有前驱,跳过
                    val durationMs = (now - previous) / 1_000_000.0
                    trace.record(now, durationMs)
                    sincePublish++
                    if (sincePublish >= publishEvery) {
                        sincePublish = 0
                        // 每 30 帧才触发一次重组,实时面板的刷新频率约 2 次/秒
                        stats.value = trace.stats()
                    }
                }
                previous = now
            }
        } finally {
            // 停止采样或组合被取消时,补发缓冲区尾部的统计,避免报告缺尾帧
            stats.value = trace.stats()
        }
    }
    return stats
}

逐行说清楚几个设计取舍。LaunchedEffect(trace, enabled) 的两个 key 保证:切换 sampling 时会取消旧协程并重启;enabled == false 时新协程立即返回,不需要在循环里反复读一个已经失效的布尔值。while (true) 看似危险,实际是 Compose 里处理帧回调的惯用写法——withFrameNanos 是挂起函数,协程被取消后它会被唤醒并抛出取消异常,不会变成忙等死循环。finally 是关键:用户点「停止并出报告」时,最后不足 30 帧的样本如果没被发布,报告的 P99 就会漏掉刚发生的长尾,所以取消路径上必须补一次 trace.stats()。

previous != 0L 的判断则处理了一个很实际的边界:第一次回调没有前驱时间戳,若拿 0 去减,会造出一个天文数字般的"帧耗时",直接把 P99 和最长帧污染掉。这类脏数据在真机上通常表现为"启动第一帧 10 万毫秒",比业务卡顿本身更容易误导排查方向。

发布周期取 30 帧,是在"实时性"和"干扰度"之间取的折中:以 17 ms 的帧间隔算,约每 0.5 秒刷新一次实时面板,人眼够用;而 trace.stats() 内部会复制并排序一份最多 4096 元素的 DoubleArray,如果每帧都做,排序与 GC 压力就会进入被测系统。这也是为什么截图里采样帧数会显示 30、630 这种整数——它们正是发布点上的累计值。

6. 统计算法:分位数、分桶与"连续慢帧段"怎么算

统计层刻意写成纯 commonMain Kotlin,不碰任何平台 API,这样 ARM64 与 X64 跑的是同一份字节码语义,也能在应用内用断言自检。完整实现如下:

package com.ohos.frameatlas.trace

import kotlin.math.ceil
import kotlin.math.floor

/** 帧耗时聚合结果,单位统一为毫秒。 */
data class FrameStats(
    val count: Int,
    val p50Ms: Double,
    val p95Ms: Double,
    val p99Ms: Double,
    val maxMs: Double,
    val slowFrameRate: Double,
    val jankBurstCount: Int,
    val buckets: List<Int>,
)

object FrameMath {
    /** 60 Hz 的单帧预算,超过即记为慢帧。 */
    const val SLOW_FRAME_THRESHOLD_MS = 16.7

    /** 五档直方图边界:0-8、8-16.7、16.7-33.3、33.3-50、>50 ms。 */
    val BUCKET_EDGES_MS: DoubleArray = doubleArrayOf(8.0, 16.7, 33.3, 50.0, Double.POSITIVE_INFINITY)

    /** 线性插值分位数;入参必须已升序排列。 */
    fun percentile(sorted: DoubleArray, p: Double): Double {
        if (sorted.isEmpty()) return 0.0
        require(p in 0.0..1.0) { "percentile must be in [0, 1]" }
        val rank = p * (sorted.size - 1)
        val lower = floor(rank).toInt()
        val upper = ceil(rank).toInt()
        if (lower == upper) return sorted[lower]
        val fraction = rank - lower
        return sorted[lower] + (sorted[upper] - sorted[lower]) * fraction
    }

    fun summarize(durationsMs: DoubleArray): FrameStats {
        if (durationsMs.isEmpty()) {
            return FrameStats(0, 0.0, 0.0, 0.0, 0.0, 0.0, 0, List(BUCKET_EDGES_MS.size) { 0 })
        }
        // 分位数在排序副本上算;分桶与连续段必须按时间原始顺序遍历
        val sorted = durationsMs.copyOf().apply { sort() }
        val buckets = MutableList(BUCKET_EDGES_MS.size) { 0 }
        var slowFrames = 0
        var consecutiveSlow = 0
        var jankBursts = 0
        for (duration in durationsMs) {
            for (index in BUCKET_EDGES_MS.indices) {
                if (duration < BUCKET_EDGES_MS[index]) {
                    buckets[index]++
                    break
                }
            }
            if (duration > SLOW_FRAME_THRESHOLD_MS) {
                slowFrames++
                consecutiveSlow++
                // 连续第二帧超阈值时才计一段,避免把单帧抖动算成卡顿段
                if (consecutiveSlow == 2) jankBursts++
            } else {
                consecutiveSlow = 0
            }
        }
        return FrameStats(
            count = durationsMs.size,
            p50Ms = percentile(sorted, 0.50),
            p95Ms = percentile(sorted, 0.95),
            p99Ms = percentile(sorted, 0.99),
            maxMs = sorted[sorted.size - 1],
            slowFrameRate = slowFrames.toDouble() / durationsMs.size,
            jankBurstCount = jankBursts,
            buckets = buckets,
        )
    }
}

这里最容易被写错的一点是排序副本与原始顺序的分工。分位数必须在升序数组上算,但"连续慢帧段"必须用时间原始顺序遍历;如果图省事直接在 sorted 上统计连续段,所有慢帧会被排到一起,结果永远是 1 段,指标彻底失去意义。所以 summarize 里只对 copyOf() 排序, for (duration in durationsMs) 仍走原数组。

第二个细节是 require(p in 0.0..1.0)。分位数函数看起来只会被内部以 0.50 / 0.95 / 0.99 调用,但它是模块里唯一暴露给外部的数值入口,一旦将来有人传 95 而不是 0.95,floor / ceil 会算出越界下标,Kotlin/Native 上直接崩进程而不是抛一个可读异常。显式守卫加一条自检用例,比在设备上抓崩溃栈便宜得多。

第三个细节是五档边界的语义。8 ms 约等于 120 Hz 的单帧预算,16.7 ms 是 60 Hz,33.3 ms 是 30 Hz,50 ms 是 20 Hz;最后用 Double.POSITIVE_INFINITY 兜底,保证任何极端长帧都一定落入某一档,buckets.sum() 恒等于 count。这条性质被写成自检用例 ramp.sumBuckets,用 0 到 100 毫秒的 101 个样本验证分桶总和与 P95 / P99 的精确值。

7. 环形缓冲、CSV 与 20 条应用内自检

采样数据不能无限增长。一次 60 秒的滚动约 3500 帧,如果每帧都往 MutableList 里 append,内存随时间线性上涨,长时间压测时监控器自己就成了内存问题。本工程用固定容量的环形缓冲,时间戳与耗时各一个原生数组,记录路径零分配:

package com.ohos.frameatlas.trace

/** 一帧样本:纳秒时间戳 + 与上一帧的间隔(毫秒)。 */
data class FrameSample(val timestampNs: Long, val durationMs: Double)

/** 固定容量环形缓冲;采样只发生在单一 UI 线程,刻意不做同步以省掉锁开销。 */
class FrameTrace(private val capacity: Int = 4096) {
    private val timestamps = LongArray(capacity)
    private val durations = DoubleArray(capacity)
    private var head = 0
    private var count = 0

    val size: Int get() = count

    fun record(timestampNs: Long, durationMs: Double) {
        if (capacity <= 0) return
        timestamps[head] = timestampNs
        durations[head] = durationMs
        head = (head + 1) % capacity
        if (count < capacity) count++
    }

    fun clear() {
        head = 0
        count = 0
    }

    /** 按"最旧到最新"的顺序复制耗时数组,供 FrameMath.summarize 使用。 */
    fun durations(): DoubleArray {
        val result = DoubleArray(count)
        // 未写满时从 0 开始;写满后 head 指向的就是最旧样本
        val start = if (count < capacity) 0 else head
        for (index in 0 until count) {
            result[index] = durations[(start + index) % capacity]
        }
        return result
    }

    fun samples(): List<FrameSample> {
        val result = ArrayList<FrameSample>(count)
        val start = if (count < capacity) 0 else head
        for (index in 0 until count) {
            val position = (start + index) % capacity
            result.add(FrameSample(timestamps[position], durations[position]))
        }
        return result
    }

    fun stats(): FrameStats = FrameMath.summarize(durations())

    /** 带表头的 CSV,可直接写入应用沙箱 filesDir 供离线分析。 */
    fun toCsv(): String = buildString {
        appendLine("index,timestamp_ns,duration_ms")
        samples().forEachIndexed { index, sample ->
            append(index).append(',').append(sample.timestampNs).append(',')
                .append(sample.durationMs).appendLine()
        }
    }
}

durations() 里的 start 判断是环形缓冲最容易写错的地方:缓冲区没写满时,有效数据从下标 0 开始;写满之后,head 指向的恰是最旧样本(因为下一次写入会覆盖它)。两种情况下都用 (start + index) % capacity 展开,就能保证输出始终按时间递增——这不仅影响 CSV 可读性,更影响"连续慢帧段"的正确性,一旦顺序乱了,卡顿段会被切得七零八落。

CSV 目前由 toCsv() 生成,宿主也已经把沙箱目录传进 Kotlin(OhosSandbox.filesDir),但落盘动作还留在待办里。这里如实说明边界:本文展示的是应用内实时归因,不是离线轨迹导出;需要跨设备对比或提交测试报告时,还得把 toCsv() 的结果写进 filesDir。把它写成"已完成"是不准确的。

第三层保障是应用内自检。鸿蒙 Native 的单元测试需要连真机,CI 与本机 gradlew check 都会被跳过,所以把断言搬进应用启动路径,直接显示在首屏。SelfCheck.run() 覆盖空数组、[10, 20, 30] 的 P50 / 最大值 / 慢帧率、0–100 斜坡数组的 P95 = 95、P99 = 99 与分桶总和、两段连续慢帧、越界分位数抛异常、容量为 4 的环形缓冲绕回顺序、CSV 表头与行数、clear() 之后状态归零,共 20 条。第一张截图里绿色的「20/20 通过」就是它在鸿蒙 Native 上实跑的结果。这套做法不替代单元测试,但能挡住"算法在 JVM 上对、在 Native 上因浮点或数组行为不同而错"这一类问题。

8. 宿主链路:ArkTS、N-API、Kotlin 三方怎么接上

移植库与统计算法都在 Kotlin 侧,最终仍要由 ArkTS 宿主托管渲染。三个文件的职责边界非常干净,完整代码如下。

ArkTS 页面只负责取上下文、创建控制器、把 Compose 组件填满屏幕:

import { ArkUIViewController, Compose } from '@cpf-kmp-cmp/compose';
import { common } from '@kit.AbilityKit';
import { deviceInfo } from '@kit.BasicServicesKit';
import nativeApi from 'libentry.so';

@Entry
@Component
struct Index {
  private controller: ArkUIViewController | undefined = undefined;

  aboutToAppear(): void {
    // 把 SDK 版本与沙箱目录一并交给 Kotlin,后者用于后续 CSV 落盘
    const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    this.controller = nativeApi.createController(deviceInfo.sdkApiVersion, context.filesDir);
  }

  build() {
    Column() {
      if (this.controller) {
        Compose({ controller: this.controller, libraryName: 'entry' })
          .width('100%')
          .layoutWeight(1)
      }
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#10121A')
  }
}

C++ 侧的 N-API 桥做参数校验,再调用 Kotlin 用 @CName 导出的入口:

#include "libkn_api.h"
#include "napi/native_api.h"
#include <cstdint>
#include <string>

namespace {
napi_value CreateController(napi_env env, napi_callback_info info) {
    napi_value args[2];
    size_t count = 2, length = 0;
    int32_t api = 0;
    // 两个参数:SDK API 等级、应用沙箱目录;目录长度设上限防异常输入
    if (napi_get_cb_info(env, info, &count, args, nullptr, nullptr) != napi_ok || count != 2 ||
        napi_get_value_int32(env, args[0], &api) != napi_ok ||
        napi_get_value_string_utf8(env, args[1], nullptr, 0, &length) != napi_ok || !length || length > 900) {
        napi_throw_type_error(env, nullptr, "Expected API level and app files directory");
        return nullptr;
    }
    std::string directory(length + 1, '\0');
    if (napi_get_value_string_utf8(env, args[1], directory.data(), directory.size(), &length) != napi_ok) {
        napi_throw_type_error(env, nullptr, "Cannot read app files directory");
        return nullptr;
    }
    // Kotlin 必须在本次调用返回前把字符串复制进自己的内存
    return reinterpret_cast<napi_value>(MainArkUIViewController(env, api, directory.data()));
}

napi_value Init(napi_env env, napi_value exports) {
    // 初始化 CMP 鸿蒙的 ArkUI 组件注册
    androidx_compose_ui_arkui_init(env, exports);
    napi_property_descriptor method = {
        "createController", nullptr, CreateController, nullptr, nullptr, nullptr, napi_default, nullptr
    };
    napi_define_properties(env, exports, 1, &method);
    return exports;
}
}  // namespace

static napi_module module = {1, 0, nullptr, Init, "entry", nullptr, {0}};
extern "C" __attribute__((constructor)) void RegisterEntryModule() {
    napi_module_register(&module);
}

Kotlin 侧的入口则把 N-API 环境转成 Compose 的主线程调度器,并挂上实验台 Composable:

package com.ohos.frameatlas

import androidx.compose.ui.window.ComposeArkUIViewController
import kotlinx.cinterop.ByteVar
import kotlinx.cinterop.CPointer
import kotlinx.cinterop.ExperimentalForeignApi
import kotlinx.cinterop.toKString
import kotlinx.coroutines.initMainHandler
import kotlin.experimental.ExperimentalNativeApi
import platform.ArkTS.ArkTS_Napi_NativeModule.napi_env
import platform.ArkTS.ArkTS_Napi_NativeModule.napi_value

/** 沙箱目录由 ArkTS 启动时传入,供后续指标落盘使用。 */
internal object OhosSandbox {
    var filesDir: String = ""
}

/** napi_init.cpp 通过 @CName 找到本函数,取回 ArkUIViewController。 */
@OptIn(ExperimentalNativeApi::class, ExperimentalForeignApi::class)
@CName("MainArkUIViewController")
fun MainArkUIViewController(env: napi_env, api: Int, filesDir: CPointer<ByteVar>): napi_value {
    // 把 N-API env 绑定为 Compose 主线程调度器的底层环境
    initMainHandler(env)
    // toKString 会复制字符串,C++ 栈上的 directory 生命周期到此为止即可
    OhosSandbox.filesDir = filesDir.toKString()
    return ComposeArkUIViewController(env) {
        FrameAtlasApp()
    }
}

这里有一个跨语言边界的老坑:C++ 的 std::string directory 是栈上对象,CreateController 返回后即失效,所以 Kotlin 必须当场 toKString() 复制一份;反过来,napi_value 只是句柄,不能当普通指针跨帧缓存。这两条在任何 KMP 鸿蒙工程里都成立,和本文的卡顿主题无关,却经常让"页面能起来但点一下就崩"的排查走偏。

出包侧则由 composeApp/build.gradle.kts 里的 publishDebugBinariesToHarmonyApp 任务负责:它 dependsOn 两个 ABI 的 linkDebugShared*,把 libkn_api.h 与 libkn.so 按 arm64-v8a / x86_64 分别拷进 example/ohos/entry。ohosMain 里 api(libs.compose.multiplatform.export) 与 export(...) 是配对的,少了前者,ArkTS 的 Compose 组件就拿不到 Kotlin 导出的视图控制器初始化符号。

9. 报告页:把移植的图表真正用起来

采样期间不显示图表,停止后才切到报告页。这不是 UI 偏好,而是测量纪律:KoalaPlot 的 BulletGraph 自带首绘动画与 Axis 子组合,如果它在滚动过程中常驻屏幕,图表自身的动画帧会混进帧间隔样本,让"归因工具"变成"噪声源"。报告页与基线负载的完整实现如下:

/** M3 基线负载:无 key、无 contentType、每项即时构造,保留可观测的重组开销。 */
@Composable
private fun BaselineList(modifier: Modifier = Modifier) {
    LazyColumn(
        modifier = modifier.padding(top = 12.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        items(1000) { index ->
            Column(
                modifier = Modifier
                    .fillMaxWidth()
                    .clip(RoundedCornerShape(10.dp))
                    .background(Color(0xFF1B1E2B))
                    .padding(12.dp),
            ) {
                Text("卡片 #$index", color = Color(0xFFE8EAF0), style = MaterialTheme.typography.bodyMedium)
                Text(
                    "帧耗时样本 ${index * 17 % 61} ms | ${index % 7} 个标签",
                    color = Color(0xFF8A8D98),
                    style = MaterialTheme.typography.bodySmall,
                )
            }
        }
    }
}

@OptIn(ExperimentalKoalaPlotApi::class)
@Composable
private fun Report(stats: FrameStats, modifier: Modifier = Modifier) {
    Column(modifier = modifier.padding(top = 12.dp)) {
        Text("采样报告", color = Color(0xFFE8EAF0), style = MaterialTheme.typography.titleMedium)
        Text(
            "P50 ${fmt(stats.p50Ms)} / P95 ${fmt(stats.p95Ms)} / P99 ${fmt(stats.p99Ms)} ms",
            color = Color(0xFFE8EAF0),
            style = MaterialTheme.typography.bodyMedium,
            modifier = Modifier.padding(top = 8.dp),
        )
        Text(
            "慢帧率 ${fmt(stats.slowFrameRate * 100)}% | 连续慢帧段 ${stats.jankBurstCount} | 最长帧 ${fmt(stats.maxMs)} ms",
            color = Color(0xFF8A8D98),
            style = MaterialTheme.typography.bodySmall,
            modifier = Modifier.padding(top = 4.dp),
        )
        Text(
            "帧耗时分布 <8 / 8-16.7 / 16.7-33.3 / 33.3-50 / >50 ms:${stats.buckets.joinToString(" / ")}",
            color = Color(0xFF8A8D98),
            style = MaterialTheme.typography.bodySmall,
            modifier = Modifier.padding(top = 4.dp),
        )
        Text(
            "下图由移植版 KoalaPlot 绘制:标线为 16.7 ms 预算,条形为 P95 帧耗时",
            color = Color(0xFF8A8D98),
            style = MaterialTheme.typography.bodySmall,
            modifier = Modifier.padding(top = 16.dp),
        )
        BulletGraphs(
            modifier = Modifier.fillMaxWidth().height(96.dp).padding(top = 8.dp),
        ) {
            bullet(FloatLinearAxisModel(0f..60f)) {
                // 16.7 ms 预算线:一眼看出 P95 是否越过 60 Hz 单帧预算
                comparativeMeasure(16.7f)
                // 紫色条形把 P95 限制在坐标轴范围内,避免空数据时条形溢出
                featuredMeasureBar(stats.p95Ms.toFloat().coerceIn(0.5f, 60f))
                // 定性区间:正常 / 丢一帧 / 丢两帧 / 更严重
                ranges(0f, 16.7f, 33.3f, 50f)
            }
        }
    }
}

这段调用把移植的价值落在了三个具体 API 上:comparativeMeasure(16.7f) 画预算标线,featuredMeasureBar(...) 画 P95 条形,ranges(...) 画五个定性区间。它们位于上游 commonMain,一个字节都没为鸿蒙改过;真正为鸿蒙新增的只有 ModifierExtensions.ohos.kt 里的手势 actual。换句话说,移植工作的产出不是"改了一堆源码",而是"让上游 77 个文件原封不动地在鸿蒙上跑起来"——这恰恰是三方库适配最理想的状态:改动面越小,跟进上游版本的成本越低。

第四、第五张截图里紫色条形长度的变化,就是 featuredMeasureBar(stats.p95Ms) 随采样窗口变化的直接结果。图表本身没有统计能力,它只是把 FrameStats 里的一个字段画出来;但正因为有这张图,"34.26 ms"和"17.14 ms"的差别不需要读者去脑子里换算,一眼就能看出来。

10. 改造前后数据对比

按征文对优化类选题的要求,把改造前后的可量化差异列成一张表。改造前指:直接依赖上游 klib(无鸿蒙目标、编译不通)、应用内没有任何帧采样、只能靠主观感受或单一平均帧耗时判断;改造后指:源码级移植 + 帧时钟采样 + 分位数/分桶报告 + 长窗口判据。测量工具与条件在表后统一说明。

#指标改造前改造后变化数据来源
1可用的鸿蒙编译目标数0(上游目标无 ohos)2(ohosArm64 + ohosX64)0 → 2Gradle 目标配置、:koalaplot:compileKotlinOhosX64 日志
2参与编译的上游源文件数0(klib 元数据不兼容,无法链接)77 个全部编译通过0 → 77Gradle 编译日志,仅 1 条上游 unchecked cast 警告
3采样引起的页面重组频率1 次 / 帧(若逐帧发布统计)1 次 / 30 帧约降低 96.7%代码级可复算:publishEvery = 30
4单次采样可得的归因维度1 类(最长帧或平均帧耗时)6 类(P50/P95/P99、慢帧率、连续慢帧段、五档分布),另可导出 CSV1 → 6应用内报告页、FrameStats 字段
5鸿蒙 Native 上通过的算法断言无法执行20 / 20—首屏自检文字(第一张截图)
6可出图的 ABI 动态库02 份:ARM64 59,384,904 B、X64 56,967,960 B0 → 2publishDebugBinariesToHarmonyApp 产物、HAP 包内条目
7可安装运行的签名 HAP构建失败61,559,097 B—hvigor assembleHap 日志
8短窗口(1093 帧)P9534.26 ms—对照基准应用内采样,第四次截图
9长窗口(3164 帧)P95—17.14 ms较对照低 17.12 ms应用内采样,第五次截图
10≥33.3 ms 长尾帧占比21.6%(236 / 1093)2.6%(81 / 3164)下降 19.0 个百分点两次报告的分布栏重算

测量工具与条件:指标 1、2、6、7 来自 Gradle 8.9 与 hvigor 的本机构建日志及 HAP 包内容清单;指标 3、4、5 来自工程源码与应用内自检,可在任意一台鸿蒙设备上复算;指标 8、9、10 来自应用内 withFrameNanos 采样,设备为 HUAWEI 手机模拟器 emulator(7.0.0.107,API 26,x86_64,127.0.0.1:5555),debug 构建,Kotlin/Native cacheKind=none,同一个 1000 卡 LazyColumn,手动持续拖动,两次独立采样分别为 1093 帧与 3164 帧,未做多轮取平均。所有帧数据均为 Compose 帧时钟口径,与 DevEco Profiler 的系统级帧数据不可直接互换;debug 包与 release 包的绝对数值也不应互相套用。

必须再写一遍边界:指标 8 到 10 描述的是采样窗口与判据对归因结论的影响,不是列表渲染性能的提升。基线 LazyColumn 在两次采样里是同一份代码,没有加 key、没有加 contentType、没有做分页。把"P95 从 34.26 降到 17.14"包装成优化效果,是把统计现象当成了性能收益。

11. 从数据里能读出的三条结论

第一条:100% 的慢帧率,先怀疑阈值,再怀疑代码。 两次报告里 P50 分别是 17.13 ms 与 17.12 ms,都高于写死的 SLOW_FRAME_THRESHOLD_MS = 16.7。也就是说,这台模拟器的 Compose 帧时钟基线本来就略超 16.7 ms,于是每一帧都被判为慢帧,slowFrameRate 恒等于 1.0,这个指标完全失去了区分能力。真正的信息藏在 P95、P99 和分桶里。跨端框架尤其容易踩这个坑:Android 上按 16.7 ms 校准的判据,换到不同刷新率、不同合成器、不同时基的设备上就会整体偏移。阈值应当来自设备实测基线,而不是写死在常量里。

第二条:34.26 ms 很像"丢一帧",不是"渲染慢了一倍"。 两次采样的 P99 都稳定在 34.26–34.27 ms,最长帧 34.27–34.28 ms,而 P50 是 17.12–17.13 ms;34.26 几乎正好是 17.13 的两倍。分桶也印证了这一点:所有样本都落在 16.7–33.3 与 33.3–50 两档,>50 ms 档始终为 0。这种整齐的倍数关系更像是跳过了一次 vsync 调度,而不是组合或绘制代码突然变慢。若真要把原因钉死,需要在同一时间轴上叠加 hiTraceMeter 区间或 DevEco Profiler 的 Frame 轨道,看这段时间里 Kotlin 侧是否仍在组合——这是本文数据能支持的最强结论,超出部分不做推断。

第三条:P95 高度依赖采样窗口长度,报告必须带帧数。 1093 帧时,5% 分位点大约对应第 55 个最慢帧,而 33.3–50 ms 桶里有 236 帧,远超分位点,所以 P95 被顶到 34.26 ms;3164 帧时,分位点对应约第 158 个最慢帧,而长尾桶只有 81 帧,P95 自然回落到 17.14 ms,P99 仍留在 34.26 ms。两次采样是独立运行、时长不同,不能据此断言"长尾都集中在冷启动",但它足以提示:短采样会把一次性的启动/首轮组合开销放大成"系统性问题"。因此任何 P95 对比都必须同时给出采样帧数、时长与滚动脚本,否则同一个应用能跑出两种完全相反的结论。连续慢帧段在两次报告里都是 1,也说明这不是持续成片的卡顿;要定位这 1 段发生在哪里,现有实现只有总量直方图,还缺按时间轴分段的视图——这是当前工具最该补的一块。

12. 踩坑与边界条件

坑一:Kotlin/Native 的 LLVM 依赖有 788 MB,而且半成品 zip 会把构建带偏。 工具链 2.2.21-1.2.0 首次执行 downloadKotlinNativeDistribution 时,需要下载 cpf-llvm-19-x86_64-windows-dev-21.zip(825,918,207 字节)。本机原先只有 dev-20,下载又被网络中断,Gradle 看到 cache 目录里那个未写完的 zip 就直接尝试解压,报 zip END header not found。镜像支持 HTTP Range,正确做法是先用 curl -L -C - 续传到临时文件名,校验字节数后再改名为正式 zip 交给 Gradle。这条流程已写进仓库 docs/BUILD.md,否则换一台机器就要重新踩一遍。

坑二:00308003 与 00302013 是一对互相牵制的错误。 本机策略禁止遍历 junction,直接调用 hvigorw 会报 00308003;于是 CLI 构建脚本用 robocopy 把 DevEco 的 hvigor、hvigor-ohos-plugin 复制成工程内 node_modules/@ohos/ 的实体副本。可一旦副本残留,DevEco 用全局 hvigorw.js --sync 时就会加载第二份 hvigor,报 00302013 Script Error: The root node is not yet available for build。排查时要先确认 hvigor/hvigor-config.json5 的 dependencies 是否为空(本工程为空,不属于官方提示的另外两种情况),再去看副本目录。最终修法是让脚本在构建前清理历史残留、构建后用 finally 无条件删除副本;实测 --sync 退出码 0、CLI assembleHap BUILD SUCCESSFUL、副本不残留,IDE 与 CLI 不再互斥。

坑三:JDK 与 SDK 版本不能想当然。 gradle.properties 用 org.gradle.java.home 固定 JDK 17.0.2,DevEco 自带的 JBR 21/25 会让 Kotlin/Native 编译器异常;kotlin.mpp.applyDefaultHierarchyTemplate=false、kotlin.native.cacheKind=none、ohosSkikoVersion=0.9.22.2-1.2.0 也必须保留。宿主侧 compatibleSdkVersion 是选题要求的 6.0.0(20),而 targetSdkVersion / compileSdkVersion 是 26.0.0,与实测设备的 API 26 对应;把三者全写成 26.0.0 看似省事,却偏离了兼容基线。鸿蒙适配版 Kotlin / CMP 插件只发布在 maven.eazytec-cloud.com 镜像上,settings.gradle.kts 里少一个仓库就会在解析插件时卡住。

坑四:上游 0.x 版本的 API 与元数据都不稳定。 KoalaPlot 明确说明 0.x 不保证二进制兼容,所以 UPSTREAM.json 必须锁死 tag 与 commit;移植时去掉 explicitApi() 但保留所有 public 修饰符,避免为了"能编译"改动公开签名。另外 api(compose.ui) / api(compose.animation) 不能降级成 implementation,因为上游公开签名直接暴露了这些包里的类型。

坑五:包名被调试签名 profile 锁住。 AppScope/app.json5 的 bundleName 与签名材料绑定;设备上若已存在同包名且 versionCode 更高的包,install -r 会被拒绝,需要先卸载。多工程共用调试签名时尤其容易撞车。

坑六:固定阈值会让"慢帧率"变成常数。 前文已用两台口径的 P50 说明 16.7 ms 在这台模拟器上把所有帧都判慢。同类问题还包括把 120 Hz 设备的 8.3 ms 预算套到 60 Hz 设备上、把帧时钟时间戳当成硬件 vsync。判据不校准,指标越精细越会误导人。

坑七:环形缓冲会悄悄丢掉最旧的长尾。 容量 4096 帧,本文两次采样 1093 / 3164 帧都未触发覆盖;但压测一旦超过 4096 帧,最旧的冷启动长尾会被覆盖,P99 与"连续慢帧段"都可能被低估。长时间压测要么加大容量,要么把 toCsv() 的结果分段落盘。

坑八:测量工具自身就是负载。 逐帧写状态会逐帧重组;图表动画常驻屏幕会引入额外帧;trace.stats() 每次复制并排序最多 4096 个元素,发布频率过高就会进入被测系统。本文用"每 30 帧发布 + 采样期隐藏图表 + 固定容量数组"三重约束把干扰压下去,但仍不能说采样零开销。

坑九:口径边界。 withFrameNanos 是 Compose 帧时钟,不是系统 vsync,也不是 GPU 绘制耗时;CSV 落盘只完成了 toCsv() 生成,写文件动作尚未接入;图表只画 P95 与总量分布,没有按时间轴分段。三者都决定了本文能回答"有没有长尾、长尾有多长、判据可不可信",还不能回答"具体是哪张卡片、哪个阶段慢"。若需要系统级交叉验证,可用 HarmonyOS 的 @ohos.graphics.displaySync(API 11+,IntervalInfo.timestamp / targetTimestamp)取设备帧预期时间,或叠加 hiTraceMeter 区间。

坑十:不要把模拟器结论直接搬到真机。 双 ABI 是为了让 ARM64 真机与 x86_64 模拟器都能装,不代表两者帧分布一致;debug 包与 release 包、模拟器与真机、手动拖动与自动滚动脚本,任何一项变了都要重新取基线。本文所有数字都只在第 0 节列出的条件下成立。

13. 结论与可直接复用的建议

回到最初的问题:KMP/CMP 鸿蒙长列表"有点卡",到底该怎么查?这套工程给出的答案是一条可复制的链路——先让三方库在双 ABI 上真正跑起来,再用低开销的帧时钟采样拿到原始数据,用分位数与分桶代替平均值,最后把基线、阈值、采样帧数一起写进报告。五张截图里最值钱的不是那张画得挺好看的 BulletGraph,而是"100% 慢帧率"这个明显不对劲的数字:它逼着我们回头检查判据,才发现设备帧间隔基线是 17.12 ms,才发现 34.26 ms 是它的两倍,才发现 P95 会随窗口长度剧烈变化。归因工具的价值,往往就体现在它能不能暴露自己身上的问题。

第一条建议:把固定阈值换成设备实测基线。下面是可直接放进 FrameMath 的完整实现,逻辑与现有 summarize 一致,只是把常量换成从 P50 推导的阈值:

/** 按设备实测基线推导阈值后重新聚合,避免固定 16.7 ms 造成的误判。 */
fun summarizeAdaptive(durationsMs: DoubleArray): FrameStats {
    if (durationsMs.isEmpty()) return FrameMath.summarize(durationsMs)
    // 分位数需要升序副本,分桶与连续段仍按原始时间顺序遍历
    val sorted = durationsMs.copyOf().apply { sort() }
    // 阈值取 P50 的 1.5 倍并设 8 ms 下限:既能放过基线附近的正常抖动,
    // 也能抓住约两倍基线的"丢一帧"。下限防止异常短的基线把阈值压得过低
    val threshold = maxOf(8.0, FrameMath.percentile(sorted, 0.50) * 1.5)

    val buckets = MutableList(FrameMath.BUCKET_EDGES_MS.size) { 0 }
    var slowFrames = 0
    var consecutiveSlow = 0
    var jankBursts = 0
    for (duration in durationsMs) {
        for (index in FrameMath.BUCKET_EDGES_MS.indices) {
            if (duration < FrameMath.BUCKET_EDGES_MS[index]) {
                buckets[index]++
                break
            }
        }
        if (duration > threshold) {
            slowFrames++
            consecutiveSlow++
            if (consecutiveSlow == 2) jankBursts++
        } else {
            consecutiveSlow = 0
        }
    }
    return FrameStats(
        count = durationsMs.size,
        p50Ms = FrameMath.percentile(sorted, 0.50),
        p95Ms = FrameMath.percentile(sorted, 0.95),
        p99Ms = FrameMath.percentile(sorted, 0.99),
        maxMs = sorted[sorted.size - 1],
        slowFrameRate = slowFrames.toDouble() / durationsMs.size,
        jankBurstCount = jankBursts,
        buckets = buckets,
    )
}

用第五次采样的数据估算:P50 为 17.12 ms,推导阈值约 25.68 ms,33.3–50 ms 桶里的 81 帧必然被计入,掉帧率落在约 2.6% 的量级,而不再是无区分度的 100%;P95、P99、分布桶仍照常输出,信息量不减。真正的列表优化(key + contentType + derivedStateOf + 分页预取)应当在这个判据下做 A/B:固定同一份滚动脚本、每档至少 3000 帧,只比较 P95 帧耗时、≥33.3 ms 帧占比、连续慢帧段数这三项,其他条件一律写进测量记录。

第二条建议:报告必须自带元数据。至少包含设备型号、API 等级、构建类型、采样帧数、采样时长、阈值来源、滚动方式。缺了帧数的 P95 无法与另一次采样比较;缺了阈值来源的慢帧率没有意义;缺了构建类型的绝对数值不应用于跨工程宣传。

第三条建议:三方库移植优先源码级,而且要留痕。锁上游 tag 与 commit,保留原许可文件,写 UPSTREAM.json 记录改动清单,能不改上游源码就不改。本工程 77 个上游文件零改动、只新增一个 ohosMain actual,就是最理想的形态:将来上游升级,diff 一眼能看完。若必须改成二进制依赖,先确认 Kotlin/Native 编译器版本与 klib 元数据一致,否则会在链接阶段付出更大代价。

第四条建议:把构建环境的坑固化进脚本。build_shell.ps1 现在会在构建前清理历史 hvigor 副本、构建后 finally 清理,并把结果打印成 HVIGOR_COPIES_CLEANED=True;这类"环境级"修复写进 README 容易被忽略,写进脚本才不会复发。LLVM 大依赖的续传与完整性校验同理,已记录在 docs/BUILD.md。

14. 复现步骤

仓库 README 写清了版本要求、依赖安装、编译与运行,这里给出最短路径(Windows PowerShell,工程放在纯 ASCII 路径下):

# 1. 克隆后进入工程
cd kmp-ohos-frame-atlas

# 2. 编译移植库与应用层(冒烟验证)
.\build_m0.ps1
.\build_m1.ps1

# 3. 构建签名 HAP:build_all.ps1 内含「生成双 ABI 动态库 + 拷入宿主 + hvigor 打包」
#    若只想要动态库,单独执行 .\gradlew.bat :composeApp:publishDebugBinariesToHarmonyApp --no-daemon
#    脚本会自行处理 hvigor 副本的创建与清理
.\build_all.ps1

# 4. 安装到设备(若报 versionCode 冲突,先卸载同包名旧应用)
hdc -t 127.0.0.1:5555 install -r .\example\ohos\entry\build\default\outputs\default\entry-default-signed.hap

也可用 DevEco Studio 直接打开 example/ohos 同步并运行;CLI 构建结束后副本已自动清理,两条路径互不干扰。应用内点击「开始采样」,持续拖动 1000 卡长列表,再点「停止并出报告」,即可得到本文五张截图对应的界面。仓库中包含 README.md、koalaplot/README.upstream.md、koalaplot/UPSTREAM.json、koalaplot/LICENSE.txt、docs/BUILD.md、LICENSE-MIT,以及分阶段的编译脚本与验证记录。

15. 参考与许可

文中所有帧数据均来自第 0 节所列实测环境,截图为应用内真实运行画面;代码与构建日志可在上述仓库复现。若需发布优化效果,请按第 13 节的 A/B 方案在目标设备上重新测量,不要用本文的基线数据代替优化后数据。

Logo

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

更多推荐