KMP/CMP 鸿蒙长列表掉帧归因:移植 KoalaPlot 绘制帧耗时分布,从 100% 慢帧率里找出真实长尾
社区引导:欢迎加入 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 Studio | 26.0.0.851(内置 hvigor / ohpm / SDK,build DS-261.23567.138.36.2600851) |
| 构建 SDK | compatibleSdkVersion 6.0.0(API 20),targetSdkVersion / compileSdkVersion 26.0.0 |
| Kotlin Multiplatform | 2.2.21-1.2.0(鸿蒙适配版,含 ohosArm64 / ohosX64 目标) |
| Compose Multiplatform | 1.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 / JDK | 8.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 通过」是移植到鸿蒙 Native 之后最重要的一道保险:分位数、慢帧率、分桶、环形缓冲绕回、CSV 表头等 20 条断言在应用进程里真实跑过,不是桌面 JVM 上的模拟结果。此时还没有任何采样帧,P50 / P95 / P99 都是 0,KoalaPlot 画出的只有一条 16.7 ms 的紫色标线和五个定性区间。这张图同时说明一件事:图表库已经能在鸿蒙 CMP 渲染链路上完成测量、布局与绘制,移植不是"能编译"而是"能出图"。

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

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

第四张图是第一次停止采样后的完整报告: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 帧后的报告。这里出现了整篇文章最值得停下来看的反直觉现象:采样帧数多了近两倍,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 以及四条改动,避免几个月后没人说得清这份代码从哪来、改过什么。
四处改动分别是:
| 序号 | 改动 | 原因 |
|---|---|---|
| 1 | Gradle 目标从 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 → 2 | Gradle 目标配置、:koalaplot:compileKotlinOhosX64 日志 |
| 2 | 参与编译的上游源文件数 | 0(klib 元数据不兼容,无法链接) | 77 个全部编译通过 | 0 → 77 | Gradle 编译日志,仅 1 条上游 unchecked cast 警告 |
| 3 | 采样引起的页面重组频率 | 1 次 / 帧(若逐帧发布统计) | 1 次 / 30 帧 | 约降低 96.7% | 代码级可复算:publishEvery = 30 |
| 4 | 单次采样可得的归因维度 | 1 类(最长帧或平均帧耗时) | 6 类(P50/P95/P99、慢帧率、连续慢帧段、五档分布),另可导出 CSV | 1 → 6 | 应用内报告页、FrameStats 字段 |
| 5 | 鸿蒙 Native 上通过的算法断言 | 无法执行 | 20 / 20 | — | 首屏自检文字(第一张截图) |
| 6 | 可出图的 ABI 动态库 | 0 | 2 份:ARM64 59,384,904 B、X64 56,967,960 B | 0 → 2 | publishDebugBinariesToHarmonyApp 产物、HAP 包内条目 |
| 7 | 可安装运行的签名 HAP | 构建失败 | 61,559,097 B | — | hvigor assembleHap 日志 |
| 8 | 短窗口(1093 帧)P95 | 34.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. 参考与许可
- KoalaPlot / koalaplot-core v0.12.1,MIT,https://github.com/KoalaPlot/koalaplot-core。本文移植的上游源码、许可原文与改动清单见仓库
koalaplot/目录。 - JetBrains Compose Multiplatform 与 Kotlin Multiplatform,
withFrameNanos、LazyColumn、LaunchedEffect等 API 的语义以官方文档为准:https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-getting-started.html。 - HarmonyOS
@ohos.graphics.displaySync(API 11+)的IntervalInfo.timestamp/targetTimestamp,用于系统 vsync 的交叉校验:https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-graphics-displaysync。 - KMP&CMP 鸿蒙社区与工具链资料:https://atomgit.com/CPF-KMP-CMP;框架与三方库提交组织:https://atomgit.com/oh-tpc。
- 本文示例仓库:https://atomgit.com/oh-tpc/kmp-ohos-frame-atlas。移植代码沿用上游 MIT,新增的鸿蒙桥接、帧统计、示例与文档采用 MIT(见
LICENSE-MIT)。
文中所有帧数据均来自第 0 节所列实测环境,截图为应用内真实运行画面;代码与构建日志可在上述仓库复现。若需发布优化效果,请按第 13 节的 A/B 方案在目标设备上重新测量,不要用本文的基线数据代替优化后数据。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)