Compose Multiplatform 三方库 MaterialKolor 的 OpenHarmony 鸿蒙化适配实战（Kotlin/Native 编译 .so + NAPI 桥接 + ArkUI 动态取色）

库版本：MaterialKolor 2.1.1（material-color-utilities 模块，Google MCU 的 Kotlin 移植）｜验证环境：Compose Multiplatform 生态 / Kotlin 2.2.21-1.0.0（鸿蒙定制版）｜DevEco Studio 26.0.0｜DevEco 模拟器｜HarmonyOS 7.0.0（API 26）

Material You 的动态取色（种子色 → 完整配色方案）是 Android 12 之后最出圈的设计语言，而鸿蒙的「一镜到底」动态主题同样需要一套从壁纸取色推导全应用配色的算法。MaterialKolor（946★）正是 Kotlin 生态里 Material You 取色算法的事实标准库——它把 Google 的 material-color-utilities 移植成了纯 Kotlin，零平台依赖、零第三方依赖。本文记录我把它完整跑上鸿蒙的全过程：从筛掉被 skiko 卡死的 Compose 渲染类库、Kotlin/Native 编译双 ABI .so、@CName + NAPI 极简切片桥接，到处理一个编译期插件注解（@Poko）的替代方案，最终在 DevEco 模拟器上用 ArkUI 做出可交互的调色板 Demo——种子色、9 种主题变体、深浅色、三档对比度，每次交互都真实穿越 ArkTS → NAPI → Kotlin/Native → MCU 算法。

*先睹为快：DevEco 模拟器实测，华为红种子色 + TONAL_SPOT 变体生成的完整配色方案* 

一、适配目标与整体链路

目标：在鸿蒙模拟器里跑一个 ArkTS 应用，切换种子色/变体/深浅色/对比度时，真实调用 Kotlin/Native 里的 Material You 取色算法，把 27 个角色色卡和 Tonal 色阶渲染出来——以此证明整条链路真正打通，而不是 UI 上摆几个写死的颜色。

整体链路：

ArkTS (Index.ets)
   │  import mkolor_napi from 'libmkolor.so'
   ▼  NAPI 调用 generateScheme(seed, variant, dark, contrast)
libmkolor.so  ← C++ NAPI 薄层
   │
   ▼  extern "C" 调用
libohosmkolor.so  ← Kotlin/Native (ohosArm64 / ohosX64)
   │
   ▼
mcu 模块 → MaterialKolor material-color-utilities（42 个纯 Kotlin 算法文件）

适配目标的最终效果：

*华为红种子 + TONAL_SPOT：27 个角色色卡全部由算法实时生成，前景色 Aa 演示真实对比度*

二、为什么是 MaterialKolor：CMP 库鸿蒙化的选型逻辑

JetBrains 官方的 Compose Multiplatform 没有 ohos target，这是所有 CMP 库鸿蒙化的共同起点。我在 oh-tpc 孵化仓盘点了一圈，把 CMP 热门库按「鸿蒙化难度」分成了三类：

类型	代表库	鸿蒙化判定
图片渲染类	Coil 3、Coil 3 Video	硬阻塞：依赖 skiko（Skia），skiko 没有 ohos target，图片解码在 Kotlin/Native 侧无现成方案
UI 特效类	Haze、Cupertino	同样卡 skiko，Compose 渲染层无法复用
纯算法类	MaterialKolor、kotlinx-serialization	零平台依赖，Kotlin/Native 直接编 .so，改造量趋近于零

MaterialKolor 的核心模块 material-color-utilities 是 Google material-color-utilities 的 Kotlin 移植：HCT 色彩空间变换、Tonal 色阶生成、动态配色推导——42 个文件全是数学，不碰 skiko、不碰 okio、不碰 coroutines。而它的 Compose 包装层（material-kolor 模块，@Composable API）在鸿蒙端由 ArkUI 替代即可。算法核心 100% 复用原库源码，这正是纯算法库适配快的根本原因。

这套算法最终能产出什么？先看一组它推导的 Tonal 色阶：

*Tonal 色阶瀑布：从一颗种子色推导出的完整色调梯度（tone 0–100）*

三、工程结构

mkolor-ohos-demo/
├── mcu/                        # 库模块：material-color-utilities 源码（42 个算法文件）
│   └── src/commonMain/kotlin/com/materialkolor/  # 100% 复用上游
├── example/
│   ├── nativeApp/              # Kotlin/Native 桥接层 → libohosmkolor.so
│   │   └── src/ohosMain/kotlin/MkolorExport.kt   # @CName 导出 C ABI
│   └── harmonyApp/             # ArkTS 鸿蒙应用
│       └── entry/src/main/
│           ├── cpp/napi_init.cpp               # C++ NAPI 薄层
│           ├── ets/pages/Index.ets             # ArkUI 调色板页面
│           └── libs/{arm64-v8a,x86_64}/        # 双 ABI .so
└── settings.gradle.kts / build.gradle.kts / gradle.properties

四、适配过程：四个关键步骤

4.1 Gradle 工程配置（鸿蒙定制工具链）

鸿蒙的 Kotlin 定制工具链（2.2.21-1.0.0）托管在 eazytec 的 Nexus 仓库，pluginManagement 里必须放第一位：

// settings.gradle.kts
pluginManagement {
    repositories {
        maven("https://maven.eazytec-cloud.com/nexus/repository/maven-public/")  // 必须第一位
        mavenCentral()
        gradlePluginPortal()
    }
}

库模块和桥接模块的 target 配置：

// mcu/build.gradle.kts（拷入 42 个算法源文件）
plugins { kotlin("multiplatform") version "2.2.21-1.0.0" }
kotlin {
    ohosArm64()
    ohosX64()
    jvm()  // 本地验证用
    sourceSets { commonMain.dependencies { /* 零依赖 */ } }
}

// example/nativeApp/build.gradle.kts
kotlin {
    ohosArm64 { binaries { sharedLib { baseName = "ohosmkolor" } } }
    ohosX64   { binaries { sharedLib { baseName = "ohosmkolor" } } }
    sourceSets { commonMain.dependencies { api(project(":mcu")) } }
}

4.2 唯一的源码改造：@Poko 注解

原库有 6 个类使用 @Poko 注解——它是一个编译期插件，自动生成 equals/hashCode/toString。鸿蒙工程没有这个插件，注解无法解析，编译直接失败。处理方式分两种情况：

• 5 个类：直接删除 @Poko 注解与 import。它们没被用作 Map key，没有 equals/hashCode 也不影响任何功能；
• Hct：被 TemperatureCache 用作 Map<Hct, Double> 的 key，删掉注解后如果不同实例的哈希不一致，查缓存就会 miss。必须手写：

// Hct.kt —— 手写替代 @Poko 生成的 equals/hashCode
override fun equals(other: Any?): Boolean = other is Hct && other.argb == argb
override fun hashCode(): Int = argb

这是全部改造量——算法源码零改动。判断标准很简单：全局搜 @Poko，再搜这些类名是否出现在 Map<、Set<、toMap 等需要哈希的泛型参数里。只有 Hct 命中。

4.3 Kotlin 出口（@CName C ABI）+ C++ NAPI 薄层

桥接遵循极简切片原则：不暴露 Kotlin 对象，只传 JSON 字符串，跨语言边界最小化。

// ohosMain/kotlin/MkolorExport.kt
@CName("OhosMkolorGenerateScheme")
fun ohosMkolorGenerateScheme(
    seedArgb: Int, variant: String, isDark: Boolean, contrastLevel: Double,
): CPointer<ByteVar> {
    val json = MkolorBridge.generateSchemeJson(seedArgb, variant, isDark, contrastLevel)
    return jsonToCString(json)  // nativeHeap 分配，null 结尾
}

@CName("OhosMkolorFree")
fun ohosMkolorFree(ptr: CPointer<ByteVar>?) {
    ptr?.let { nativeHeap.free(it.rawValue) }  // 谁分配谁释放
}

C++ 侧是薄薄一层，拿到字符串后立即释放，零拷贝持有：

// napi_init.cpp
extern "C" {
const char *OhosMkolorGenerateScheme(int, const char *, int, double);
void OhosMkolorFree(const char *);
}

static napi_value NapiGenerateScheme(napi_env env, napi_callback_info info) {
    // 参数解析：seedArgb 按 uint32 取再转 int（0xFFCF0A2C 超 INT32_MAX）
    const char *raw = OhosMkolorGenerateScheme(seed, variant.c_str(), isDark, contrast);
    napi_value out;
    napi_create_string_utf8(env, raw, NAPI_AUTO_LENGTH, &out);
    OhosMkolorFree(raw);  // 用完立即释放
    return out;
}

ArkTS 侧一行调用：

// Index.ets 核心调用
const raw: string = mkolor_napi.generateScheme(
  seed.argb, VARIANTS[this.variantIdx], this.isDark, this.contrastLevel)
this.scheme = JSON.parse(raw) as SchemeJson

4.4 编译与部署

# 1. 编译双 ABI release .so（JDK 21 作为 JAVA_HOME）
$env:JAVA_HOME = "C:/Users/nwu/Desktop/z_pig/jdk-21.0.2"
.\gradlew.bat :example:nativeApp:linkReleaseSharedOhosArm64 `
              :example:nativeApp:linkReleaseSharedOhosX64

# 2. 部署到 entry/libs（含 Kotlin/Native 运行时 libc++_shared.so）
entry/libs/arm64-v8a/libohosmkolor.so
entry/libs/x86_64/libohosmkolor.so

# 3. 构建 HAP（注意把 JAVA_HOME\bin 前置到 PATH）
$env:Path = "$env:JAVA_HOME\bin;" + $env:Path
hvigorw.js --mode module -p module=entry@default assembleHap

# 4. 安装到模拟器
hdc install -r entry-default-unsigned.hap

跑起来之后，切深色模式整套配色会实时重新生成——这正好验证编译产物真的在工作：

*深色模式：同一颗种子色推导出的暗色方案，背景/表面色整体下压*

五、踩坑记录（3 个）

坑	现象	解法
hilog 链接失败	undefined symbol OH_LOG_Print	CMakeLists 加 libhilog_ndk.z.so
ArkTS 保留字	@State contrast 与 CustomComponent 基类属性冲突	改名 contrastLevel
打包找不到 java	spawn java ENOENT（00308018 Unknown Error）	构建 PATH 前置 JAVA_HOME\bin

六、运行效果（DevEco 模拟器实测）

Demo 做成深色高级 UI，四大交互全走真实 NAPI：种子色（6 个预置色圆点：华为红/海洋蓝/青碧/琥珀/紫罗兰/松绿）、主题变体（9 种 Variant 胶囊）、深浅色 + 三档对比度（-1/0/1）、展示（27 个角色色卡 + 3 组 Tonal 色阶瀑布）。

切到 EXPRESSIVE 变体，色相偏移明显，风格焕然一新：

*EXPRESSIVE 变体：色相偏移更大，饱和度更高，风格更张扬*

换成海洋蓝种子色，整套方案跟随变化：

*海洋蓝种子 + EXPRESSIVE：从红到蓝，算法对任意种子色都成立*

底部完整色阶一览：

*页面底部：Neutral Variant 色阶与完整配色总览*

真实性验证（hilog）——每次交互都有日志铁证：

MkolorNapi: generateScheme seed=-3208660 variant=TONAL_SPOT dark=0   # 华为红 0xFFCF0A2C
MkolorNapi: generateScheme seed=-3208660 variant=EXPRESSIVE dark=0   # 切变体
MkolorNapi: generateScheme seed=-14575885 variant=EXPRESSIVE dark=0  # 海洋蓝 0xFF2196F3
MkolorNapi: generateScheme seed=-14575885 variant=EXPRESSIVE dark=1  # 切深色

seed=-3208660 正是 0xFFCF0A2C 的有符号 int 表示——每次交互都真实穿越 ArkTS → NAPI → Kotlin/Native → MCU 算法，非 mock。单次 generateScheme 延迟 < 1ms（纯内存计算）。

七、FAQ

Q1：为什么不用 Compose Multiplatform 直接在鸿蒙上跑 UI？JetBrains 官方 CMP 没有 ohos target，业界落地形态就是 Kotlin/Native 逻辑库 + .so + NAPI + ArkUI 页面（oh-tpc 已适配的 cmp_qrose 也是这条路线）。

Q2：哪些 CMP 库鸿蒙化会被卡死？依赖 skiko 的都卡（Coil 3、Haze、Cupertino 等）。判断方法：看库的 nonAndroidMain 依赖里有没有 skiko。纯算法库（序列化、色彩、数学）是最优解。

Q3：@Poko 注解编译失败怎么办？它是编译期插件，鸿蒙工程没有。删注解前先确认该类是否被用作 Map/Set 的 key——是则手写 equals/hashCode（本文只有 Hct 命中），否则直接删。

Q4：NAPI 传种子色为什么是负数？0xFFCF0A2C 超 INT32_MAX，作为 Kotlin Int 就是有符号负数。C++ 侧按 uint32_t 取再转 int 即可，算法内部按位运算不受影响。

Q5：hvigor 打包报 spawn java ENOENT（00308018）？把 JAVA_HOME\bin 前置到 PATH 再执行 hvigorw，DevEco 自带的 JBR 环境变量有时不生效。

Q6：ArkTS 状态变量叫 contrast 报错？contrast 与 CustomComponent 基类属性冲突，改名 contrastLevel。

八、总结与参考

把 MaterialKolor 跑上鸿蒙，本质还是打通 CMP 算法层 → Kotlin/Native(ohos target) → .so → NAPI → ArkTS 这条链，但这次验证了一条可复制的方法论：选型先筛 skiko——Compose 渲染类库全部卡死在 skiko，纯算法库改造量趋近于零（本文全部改造 = 删 6 个注解 + 手写 1 个 equals）；桥接走极简切片——@CName C ABI + JSON 字符串，跨语言边界最小；验收要打日志——hilog 的 NAPI 调用记录是「真实跑通」的铁证。Material You 动态取色填补了鸿蒙色彩算法类的空白，可直接用于动态主题（壁纸取色 → 全应用配色）、深浅色自动适配、无障碍对比度增强（contrastLevel ±1）。

• 上游库：https://github.com/jordond/MaterialKolor
• 鸿蒙定制仓库：https://maven.eazytec-cloud.com/nexus/repository/maven-public/
• OpenHarmony 三方库社区：https://atomgit.com/oh-tpc
• OpenHarmony 三方库适配地址：https://atomgit.com/oh-tpc/MaterialKolor
• 欢迎加入 KMP&CMP 鸿蒙社区：https://atomgit.com/CPF-KMP-CMP