Kuikly 鸿蒙端接入与使用简介

一、Kuikly 是什么

Kuikly 是腾讯开源的、基于 Kotlin Multiplatform(KMP)的超高性能动态化框架。一套 Kotlin 代码可以同时运行在 Android、iOS、鸿蒙、H5、小程序等多个平台,帮助业务实现"一次开发、多端运行"。

  • 官方文档:https://kuikly.tds.qq.com/DevGuide/dev-guide-overview.html
  • GitHub:https://github.com/Tencent-TDS/KuiklyUI

在鸿蒙端,Kuikly 的业务代码(Kotlin)会被编译为 .so 动态库,由基于 ArkUI C-API 实现的鸿蒙渲染器负责渲染,最终以 ArkTS 组件的形式嵌入到鸿蒙应用中。

二、整体架构

┌──────────────────────────────────┐
│     KMP 业务工程(shared 模块)    │
│   Kotlin 跨端代码 → 编译为各端产物  │
│   鸿蒙端产物:libshared.so + 头文件 │
└───────────────┬──────────────────┘
                │ 依赖
                ▼
┌──────────────────────────────────┐
│         鸿蒙宿主工程(ohosApp)     │
│  @kuikly-open/render 渲染器        │
│  Kuikly 组件(ArkUI C-API)        │
│  NAPI 桥接 + 适配器                │
└──────────────────────────────────┘

核心思路是:业务逻辑写在 shared 模块(跨端),鸿蒙端只负责"接入渲染器 + 提供原生能力"。

三、接入前的准备

  • 已完成 KMP 侧 shared 模块的 Kuikly 接入(core、core-annotations 等依赖)
  • 鸿蒙开发环境:DevEco Studio(注意:鸿蒙模拟器不支持 X86 版 Mac,推荐 Apple Silicon 版 Mac)
  • 各端 Kuikly 版本号保持一致(shared 模块与鸿蒙渲染器版本必须相同)

四、鸿蒙端接入步骤(五步走)

1. 添加渲染器依赖

在 entry 模块的 oh-package.json5 中添加:

{
  "dependencies": {
    "@kuikly-open/render": "KUIKLY_RENDER_VERSION"  // 替换为实际版本
  }
}

点击 Sync Now 或执行 ohpm install。

2. 创建运行时初始化接口(NAPI)

Kuikly 鸿蒙渲染基于 ArkUI C-API,需要通过 NAPI 把初始化接口暴露给 ArkTS:

  • 在 entry 模块添加 Native C++ 支持
  • 在 napi_init.cpp 中实现 InitKuikly 入口函数,并注册到模块导出表
  • 在 index.d.ts 中声明:export const initKuikly: () => number;
  • 创建 MyNativeManager.ets 继承 KuiklyNativeManager,在 loadNative() 中调用 Napi.initKuikly()

3. 实现承载容器

  • 创建 KuiklyViewDelegate.ets(继承 IKuiklyViewDelegate),用于注册自定义 Module
  • 在页面(如 Index.ets)中使用 Kuikly 组件承载跨端页面:
Kuikly({
  pageName: this.pageName ?? 'router',   // 对应 @Page 注解的页面名
  pageData: this.pageData ?? {},         // 页面参数
  delegate: this.kuiklyViewDelegate,
  nativeManager: globalNativeManager,
})

同时在页面的 onPageShow / onPageHide 中转发生命周期(pageDidAppear / pageDidDisappear)。

4. 实现并注册适配器

Kuikly 通过适配器把原生能力委托给宿主实现:

适配器是否必须说明
日志适配器(IKRLogAdapter)推荐对接 hilog
路由适配器(IKRRouterAdapter)必须openPage / closePage,对接 @ohos.router
图片加载适配器按需在 C++ 层通过 KRRegisterImageAdapterV3 注册
字体 / 颜色适配器按需C++ 层 KRRegisterFontAdapter / KRRegisterColorAdapter

在 EntryAbility.ets 的 onWindowStageCreate 中注册:

KuiklyRenderAdapterManager.krLogAdapter = new LogAdapter();
KuiklyRenderAdapterManager.krRouterAdapter = new RouterAdapter();

多 Ability 场景建议把初始化提前到 AbilityStage,避免相互覆盖。

5. 链接业务代码(.so 产物)

  1. 在 KMP 工程编译鸿蒙产物:
    ./gradlew -c settings.ohos.gradle.kts :shared:linkOhosArm64
    
  2. 将生成的 libshared.so 和头文件 libshared_api.h 拷贝到 C++ 模块目录
  3. 修改 CMakeLists.txt,把 kuikly_shared 链接到 entry 模块
  4. 在 InitKuikly 中调用业务代码入口:
    auto api = libshared_symbols();
    int handler = api->kotlin.root.initKuikly();
    
  5. 如有资源文件,把 shared/src/commonMain/assets/ 拷贝到 entry/src/main/resources/resfile/

五、编写页面与验证

业务页面写在 shared 模块中,用 @Page 注解标记:

@Page("test")
class TestPage : Pager() {
    override fun body(): ViewBuilder = {
        attr {
            allCenter()
            backgroundColor(Color.WHITE)
        }
        Text {
            attr {
                fontSize(20f)
                color(Color.GREEN)
                text("Hello Kuikly")
            }
        }
    }
}

用 DevEco Studio 打开鸿蒙工程运行,页面正常显示绿色 “Hello Kuikly” 即接入成功。

补充:除了传统 Kuikly DSL(attr{} 写法),Kuikly 还支持 Compose DSL(@Composable + Modifier 写法),熟悉 Jetpack Compose 的开发者可以选用,通过脚手架 --dsl compose 参数即可生成对应工程。

六、快速起步:脚手架一键生成

如果是从零开始,推荐直接用官方脚手架生成包含鸿蒙壳工程的完整接入工程:

npx --yes @kuikly-ai/create-kuikly-app@latest --json create-integration MyApp --package com.example.myapp

生成的工程目录中包含 ohosApp/(鸿蒙壳工程,已含 Kuikly 组件、Adapter、Module 示例)和 shared/(KMP 业务模块),用 DevEco Studio 打开 ohosApp 即可直接运行,省去手动接入的繁琐步骤。

七、接入检查清单

  • oh-package.json5 已添加 @kuikly-open/render(版本与 KMP 一致)
  • 已添加 C++(NAPI)支持,实现 InitKuikly 入口
  • 已创建 MyNativeManager.ets 关联 KuiklyNativeManager
  • 已创建 KuiklyViewDelegate.ets 并实现 Kuikly 承载页面
  • 日志、路由适配器已实现并在 EntryAbility 中注册
  • .so 业务产物已编译并链接(CMakeLists.txt)
  • 资源文件已拷贝到 resfile/
  • TestPage 验证通过

八、小结

Kuikly 鸿蒙端接入的本质可以概括为一句话:跨端业务写 Kotlin(shared 模块),鸿蒙端做好三件事——接渲染器、实现适配器、链接 .so 产物。接入完成后,业务页面的开发就完全回归到 Kotlin 跨端开发,鸿蒙端无需再重复实现业务逻辑,真正实现一套代码多端运行。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐