Compose Multiplatform 三方库 KMPalette 的 OpenHarmony 鸿蒙化适配实战Kotlin/Native 编译 .so NAPI 像素级桥接 ArkUI 图片取色库版本KMPalette 2.1.0androidx-palette 模块Google Palette 的 Kotlin 移植验证环境Compose Multiplatform 生态 / Kotlin 2.2.21-1.0.0鸿蒙定制版DevEco Studio 26.0.0DevEco 模拟器HarmonyOS 7.0.0API 26「从一张图片里提取主色调」是动态主题的第一步——Android 12 的 Material You 从壁纸取色鸿蒙的「一镜到底」同样需要从壁纸提取主题色。KMPalette296★是 Kotlin 生态里图片取色的事实标准库它把 Google 的 androidx.palette 移植成了纯 Kotlin核心算法只有 8 个文件、只依赖kotlin.math零平台依赖。本文记录我把它完整跑上鸿蒙的全过程与上一篇 MaterialKolor种子色 → 配色方案正好组成完整故事——KMPalette 负责图片 → 主色调MaterialKolor 负责主色调 → 全应用配色两库串联就是鸿蒙动态主题的完整算法链。这次的新课题是像素级桥接68 万个像素如何高效穿越 ArkTS → NAPI → Kotlin/Native。*先睹为快DevEco 模拟器实测KMPalette 官方演示图提取的主色调 六大目标色 全部色板取色耗时 6ms* 一、适配目标与整体链路目标在鸿蒙模拟器里跑一个 ArkTS 应用切换测试图片时真实调用Kotlin/Native 里的 androidx.palette 取色算法把主色调Dominant、六大目标色Vibrant/Light Vibrant/Dark Vibrant/Muted/Light Muted/Dark Muted、全部色板Swatches渲染出来——以此证明整条链路真正打通而不是 UI 上摆几个写死的颜色。整体链路ArkTS (Index.ets) │ import kpalette_napi from libkpalette.so │ PixelMap → readPixelsToBuffer → ArrayBufferARGB_8888 像素 ▼ NAPI 调用 generatePalette(buffer, width, height) libkpalette.so ← C NAPI 薄层 │ ▼ extern C 调用 libohospalette.so ← Kotlin/Native (ohosArm64 / ohosX64) │ ▼ palette 模块 → androidx-palette8 个纯 Kotlin 算法文件与 MaterialKolor 适配纯标量入参最大的不同这次的输入是整张图的像素。1090×624 的演示图就是 68 万个像素、2.7MB 数据跨语言边界的传输方式直接决定成败——这是本文的核心看点。二、为什么是 KMPalette与 MaterialKolor 串联的完整故事上一篇 MaterialKolor 适配验证了「种子色 → 完整配色方案」但种子色从哪来Material You 的答案是壁纸取色。在 Kotlin 生态里这个「图片 → 主色调」的环节由 KMPalette 承担环节库输入 → 输出鸿蒙化状态图片 → 主色调KMPaletteandroidx-palette像素 → Dominant/六大目标色本文主色调 → 配色方案MaterialKolormaterial-color-utilities种子色 → 27 角色色 Tonal 色阶上一篇已完成两库串联 壁纸 → 主色调 → 全应用配色鸿蒙动态主题的完整算法链就此闭环。选型时同样先过 skiko 筛查KMPalette 的核心模块androidx-palette是 androidx Palette 的 Kotlin 移植8 个文件全是色彩量化算法颜色直方图、VBox 切分、目标色匹配只依赖kotlin.math不碰 skiko、不碰 okio、不碰 coroutines。它的 Compose 包装层kmpalette-corerememberDominantColorState等在鸿蒙端由 ArkUI 替代即可。算法核心 100% 复用原库源码。三、工程结构kmpalette-ohos-demo/ ├── palette/ # 库模块androidx-palette 源码8 个算法文件 │ └── src/commonMain/kotlin/com/kmpalette/palette/ # 100% 复用上游 ├── example/ │ ├── nativeApp/ # Kotlin/Native 桥接层 → libohospalette.so │ │ └── src/ │ │ ├── commonMain/kotlin/PaletteBridge.kt # 算法包装 JSON 序列化 │ │ └── ohosMain/kotlin/PaletteExport.kt # CName 导出 C ABI │ └── ohosApp/ # ArkTS 鸿蒙应用 │ └── entry/src/main/ │ ├── cpp/napi_init.cpp # C NAPI 薄层像素 ArrayBuffer → int* │ ├── ets/pages/Index.ets # ArkUI 取色页面 │ └── libs/{arm64-v8a,x86_64}/ # 双 ABI .so └── settings.gradle.kts / build.gradle.kts / gradle.properties四、适配过程四个关键步骤### 4.1 Gradle 工程配置鸿蒙定制工具链与 MaterialKolor 适配完全同构pluginManagement第一位放 eazytec Nexus 仓库Kotlin2.2.21-1.0.0定制版库模块与桥接模块声明ohosArm64()ohosX64()双 target// palette/build.gradle.kts拷入 8 个算法源文件plugins{kotlin(multiplatform)version2.2.21-1.0.0}kotlin{ohosArm64()ohosX64()sourceSets{commonMain.dependencies{/* 零依赖 */}}}// example/nativeApp/build.gradle.ktskotlin{ohosArm64{binaries{sharedLib{baseNameohospalette}}}ohosX64{binaries{sharedLib{baseNameohospalette}}}sourceSets{commonMain.dependencies{api(project(:palette))}}}4.2 源码改造两类注解的清理androidx-palette 上游带着 Android 的历史包袱两类注解在鸿蒙工程里都无法解析androidx.annotationColorInt、FloatRange、IntRange纯装饰性注解删 import 删用法即可。坑在三种形态独立行ColorInt\n val rgb: Int、行内参数ColorInt color: Int,、属性前缀get:ColorInt——正则要分别处理Poko编译期插件Palette和Swatch两个类在用。这次运气好——两个类都没被用作 Map key算法内部用ArrayList持有 Swatch直接删注解与 import无需手写 equals/hashCode。判断方法与上一篇相同全局搜Poko再搜类名是否出现在Map、Set泛型参数里。这次零命中算法源码零逻辑改动。4.3 像素级桥接这次的核心课题与 MaterialKolor4 个标量入参不同KMPalette 的输入是整张图的像素。跨语言边界设计ArkTS 侧——PixelMap 读出 ARGB_8888 的 ArrayBuffer连同宽高一起传给 NAPI// Index.ets 核心调用constpixelMap:image.PixelMapawaitsource.createPixelMap({desiredPixelFormat:image.PixelMapFormat.ARGB_8888})constinfoawaitpixelMap.getImageInfo()constbyteCountinfo.size.width*info.size.height*4// 每像素 4 字节constbuffernewArrayBuffer(byteCount)awaitpixelMap.readPixelsToBuffer(buffer)constraw:stringkpalette_napi.generatePalette(buffer,info.size.width,info.size.height)constparsedJSON.parse(raw)asPaletteJsonC NAPI 层——napi_get_arraybuffer_info拿到裸指针校验byteLength / 4 width * height后直接把int*传下去零拷贝// napi_init.cppvoid*datanullptr;size_t byteLength0;napi_get_arraybuffer_info(env,args[0],data,byteLength);constintpixelCountstatic_castint(byteLength/4);if(pixelCount!width*height){/* range error */}constchar*rawOhosPaletteGenerate(static_castconstint*(data),pixelCount,width,height);// raw 是 JSON 字符串转 napi string 后立即 OhosPaletteFree(raw)Kotlin 侧——CName导出 C ABI把CPointerIntVar拷贝为IntArray后立即交给算法// PaletteExport.ktCName(OhosPaletteGenerate)funohosPaletteGenerate(pixelsPtr:CPointerIntVar?,pixelCount:Int,width:Int,height:Int,):CPointerByteVar{valjsontry{requireNotNull(pixelsPtr){pixelsPtr is null}require(pixelCountwidth*height){size mismatch}valpixelsIntArray(pixelCount){i-pixelsPtr[i]}// 一次性拷贝PaletteBridge.generatePaletteJson(pixels,width,height)}catch(t:Throwable){{\error\:\${t.message?:unknown}\}}returnjsonToCString(json)// nativeHeap 分配null 结尾}CName(OhosPaletteFree)funohosPaletteFree(ptr:CPointerByteVar?){ptr?.let{nativeHeap.free(it.rawValue)}// 谁分配谁释放}像素内存的所有权链ArkTS 的 ArrayBuffer 由 NAPI 直接读裸指针零拷贝→ Kotlin 侧IntArray(pixelCount) { i - pixelsPtr[i] }一次性拷入 Kotlin 堆之后 C 侧 buffer 可任意释放→ 返回的 JSON 字符串在 nativeHeap 分配C 侧转成 napi string 后立即OhosPaletteFree。每个环节谁分配谁释放无泄漏无悬垂。PaletteBridge把Palette.from(pixels, width, height).generate()的结果序列化为 JSON全部 Swatchrgb population hsl、六大目标色无匹配为 null、主色调。4.4 编译与部署# 1. 编译双 ABI release .so.\gradlew.bat :example:nativeApp:linkReleaseSharedOhosArm64 :example:nativeApp:linkReleaseSharedOhosX64# 2. 部署到 entry/libs含 Kotlin/Native 运行时 libc_shared.soentry/libs/arm64-v8a/libohospalette.so entry/libs/x86_64/libohospalette.so# 3. 构建 HAP命令行JAVA_HOME 指向 DevEco JBR DEVECO_SDK_HOME 指向 sdk 根目录$env:JAVA_HOME C:/Program Files/Huawei/DevEco Studio/jbr$env:DEVECO_SDK_HOME C:/Program Files/Huawei/DevEco Studio/sdkhvigorw.bat assembleHap--mode module-p productdefault# 4. 安装到模拟器注意hdc 的路径参数必须用反斜杠hdc-t 127.0.0.1:5555 install-r entry-default-unsigned.hap五、踩坑记录4 个坑现象解法注解三种形态ColorInt删不干净独立行/行内参数/get:前缀正则分别处理 CRLF 行尾\r?cinterop 下标pixelsPtr[i]unresolved referenceimport kotlinx.cinterop.get运算符扩展函数DEVECO_SDK_HOME命令行 hvigor 报 00303217/00303312显式指向DevEco Studio/sdk根目录含 default/hms/openharmonyhdc 路径解析install报 no such file正斜杠路径被拼接错乱本地路径一律用反斜杠C:\...另一个值得记录的坑ArkTS 严格模式的 Record 索引。palette.targets[name]在 ForEach 渲染里既报「Object is possibly null」又不好收窄最终方案是在数据层把 Record 展开为类型化数组TargetItem[]渲染层只消费数组——ArkTS 的 UI 语法里连const局部声明都不允许视图模型化是正解。六、运行效果DevEco 模拟器实测Demo 做成深色 UI三张测试图片KMPalette 官方演示图 / 品牌 Logo / 壁纸截图一键切换每次切换都真实走一遍 像素读取 → NAPI → 取色算法 → JSON 回传 → ArkUI 渲染。官方演示图1090×62468 万像素——主色调#E0E8F0、六大目标色、全部色板一次到位取色耗时6ms*官方演示图主色调 #E0E8F0pop 1339 六大目标色#F09050 鲜活 / #B0D0E0 浅鲜活 / #2030A0 深鲜活 / #707080 柔和… 全部色板取色 6ms*品牌 Logo932×368——紫色系图片色板整体偏移*品牌 Logo算法对紫色系图片输出完全不同的色板组合*壁纸截图1320×2232294 万像素——深色系壁纸*壁纸截图294 万像素 4ms 完成取色深色系色板*真实性验证hilog——每次切换都有日志铁证KpaletteNapi: generatePalette w1090 h624 pixels680160 KpaletteNapi: generatePalette result len1447 head{swatches:[{rgb:-5189408,population:650,... KpaletteNapi: generatePalette w1320 h2232 pixels2946240 KpaletteNapi: generatePalette result len1368 head{swatches:[{rgb:-16740144,... KpaletteNapi: generatePalette w932 h368 pixels342976 KpaletteNapi: generatePalette result len1448 head{swatches:[{rgb:-9947008,...三张图三个不同的len与首 Swatch——算法对不同图片真实产出不同色板非 mock。294 万像素的壁纸取色仅 4ms色彩量化的 VBox 切分对像素数不敏感68 万像素 6ms——纯内存计算无任何 IO。七、FAQQ168 万像素跨 NAPI 会不会很慢不会。ArrayBuffer 走napi_get_arraybuffer_info拿裸指针零拷贝Kotlin 侧一次IntArray拷贝~2.7MB memcpy实测全流程 4–6ms。Q2为什么不用 PixelMap 直接传NAPI 跨语言边界传裸数据ArrayBuffer/int*最稳传对象PixelMap 句柄需要跨运行时引用管理复杂度陡增。极简切片原则边界上只传数据和 JSON 字符串。Q3ARGB_8888 的字节序对得上吗ArkTS 侧readPixelsToBuffer出来的是大端 ARGB 打包的 32 位序列按int32读取后与 KotlinInt位表示一致算法内部位运算rgb 16 0xFF不受符号影响。Q4Poko这次为什么能直接删判断标准是类是否被用作 Map/Set key——Palette/Swatch都只在ArrayList里没有哈希需求。上一篇的Hct命中过这次零命中。Q5命令行构建 HAP 报 DEVECO_SDK_HOME 错误DEVECO_SDK_HOME要指向DevEco Studio/sdk根目录下面有 default/hms/openharmony指到sdk/default会报「找不到对应 SDK 版本」00303312。Q6hdc 传文件报 no such filehdc 对正斜杠本地路径的拼接有 buginstall/file recv的本地路径一律用反斜杠。八、总结与参考KMPalette 适配完成与 MaterialKolor 串联后鸿蒙动态主题的算法链完整闭环壁纸像素 →KMPalette→ 主色调 →MaterialKolor→ 27 角色色 Tonal 色阶 → ArkUI 渲染。本篇验证的方法论增量是像素级桥接ArrayBuffer 零拷贝读指针 Kotlin 侧一次性 IntArray 拷贝 JSON 字符串回传全流程 4–6ms——证明 Kotlin/Native .so 不只能接标量也能高效接大数据。改造量依旧趋近于零删注解 零逻辑改动再次印证「选型先筛 skiko纯算法库优先」的选型逻辑。OpenHarmony 三方库社区地址https://atomgit.com/oh-tpcOpenHarmony 三方库适配地址https://atomgit.com/oh-tpc/KMPalettegithub 三方库地址https://github.com/jordond/KMPalette官方文档地址https://github.com/jordond/KMPalette/blob/main/README.md鸿蒙定制仓库地址https://maven.eazytec-cloud.com/nexus/repository/maven-public/鸿蒙适配版https://atomgit.com/oh-tpc/KMPalette
