Kuikly鸿蒙端接入与使用简介
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 产物)
- 在 KMP 工程编译鸿蒙产物:
./gradlew -c settings.ohos.gradle.kts :shared:linkOhosArm64 - 将生成的
libshared.so和头文件libshared_api.h拷贝到 C++ 模块目录 - 修改
CMakeLists.txt,把kuikly_shared链接到 entry 模块 - 在
InitKuikly中调用业务代码入口:auto api = libshared_symbols(); int handler = api->kotlin.root.initKuikly(); - 如有资源文件,把
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 跨端开发,鸿蒙端无需再重复实现业务逻辑,真正实现一套代码多端运行。
更多推荐


所有评论(0)