企业官网建设流程全解析

Kuikly Android接入指南：如何在现有项目中快速集成跨端页面

【免费下载链接】KuiklyUI基于KMP技术的高性能、全平台开发框架，具备统一代码库、极致易用性和动态灵活性。 Provide a high-performance, full-platform development framework with unified codebase, ultimate ease of use, and dynamic flexibility. 注意：本仓库为Github仓库镜像，PR或Issue请移步至Github发起，感谢支持！项目地址: https://gitcode.com/Tencent-TDS/KuiklyUI

本文手把手讲解Kuikly Android 接入全流程：以你现有的 Android 工程为例，按 6 个步骤完成Kuikly 跨端页面集成——添加渲染器依赖、实现承载容器、配置必选适配器、编写测试页面验证。Kuikly 是基于 KMP（Kotlin Multiplatform）的高性能跨端开发框架，一份 Kotlin 页面代码即可同时运行在 Android、iOS 与鸿蒙上。

📌 快速导航

• 一、先认识 Kuikly：跨端页面如何跑在 Android 上
• 二、集成准备：用脚手架插件 3 步创建 Kuikly KMP 工程
• 三、添加 Kuikly 渲染器依赖：只需几行 Gradle 代码
• 四、实现承载容器：Activity 与 View 两种接入方式
• 五、实现必选适配器：图片、日志、路由、线程四件套
• 六、编写 TestPage 验证集成是否成功
• 七、把 Kuikly 业务代码集成到现有工程
• 八、收尾配置：AndroidManifest、混淆与键盘
• 九、调试与性能排查技巧
• 常见问题 FAQ

一、先认识 Kuikly：跨端页面如何跑在 Android 上

在开始 Kuikly Android 接入之前，先用 1 分钟理解它的架构，后面每一步配置都会豁然开朗：

• Core 层：Kotlin 声明式 UI 框架（BuildTree、FlexBox 布局引擎、测量引擎），完全平台无关，你的页面代码就写在这里；
• Render 层：把 Core 层生成的 UI 树映射为各平台的原生视图。Android 上由core-render-android模块负责，直接复用原生 View 体系，所以性能接近原生；
• callNative / callKotlin：Kotlin 与原生之间的双向调用通道，配合 Module/Adapter 机制实现网络、存储等能力复用。

这种分层带来三个直接好处：统一代码库（一套 Kotlin 写多端页面）、极致性能（内置模式渲染接近原生）、动态灵活（支持 JS 动态化模式，页面可热更新）。

二、集成准备：用脚手架插件 3 步创建 Kuikly KMP 工程

Kuikly 接入分为两侧：KMP 跨端侧（写业务页面）和Android 宿主侧（本文重点）。跨端侧可以先用 Kuikly 脚手架插件一键创建工程。

1️⃣ 安装插件：在 Android Studio 中安装 Kotlin 与 Kotlin Multiplatform Mobile 插件。

2️⃣ 新建工程：File -> New -> New Project，选择Kuikly Project Template模板。

3️⃣ 检查版本号：新建后请将各配置文件中 Kuikly 版本号统一为最新版本（shared/build.gradle.kts、androidApp/build.gradle.kts、iosApp/Podfile等），各端版本号必须保持一致；2.5.0 版本起需要添加腾讯云 maven 源。

创建完成后的工程结构如下，其中shared 模块就是你编写跨端页面代码的地方：

📖 跨端侧的完整接入说明见官方文档 docs/QuickStart/common.md

三、添加 Kuikly 渲染器依赖：只需几行 Gradle 代码

在宿主工程中承载 Kuikly 页面的模块（通常是 app 模块）的build.gradle中添加两个依赖：

dependencies { implementation("com.tencent.kuikly-open:core-render-android:KUIKLY版本") // 渲染器 implementation("com.tencent.kuikly-open:core:KUIKLY版本") // 核心库 }

⚠️两个关键注意点：

1. core-render-android与core的版本号，必须和 KMP 跨端工程使用的 Kuikly 版本完全一致，否则会出现兼容性问题；最新版本号可在 docs/ChangeLog/changelog.md 查看；
2. 2.5.0 版本后需要添加 maven 源：maven("https://mirrors.tencent.com/repository/maven-tencent/")。

渲染器模块的源码位于 core-render-android/，它会把 Kuikly 的 UI 树翻译成 Android 原生 View（KRView、KRListView、KRScrollView 等）。

四、实现承载容器：Activity 与 View 两种接入方式

方式 A：Activity 接入（整页场景，最常用）

新建一个KuiklyRenderActivity作为 Kuikly 页面的承载容器，核心流程是"创建处理器 → 实例化 Delegator → 打开页面 → 转发生命周期"四步：

override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // 1. 创建页面打开的封装处理器（pageName 从 Intent 中读取） contextCodeHandler = ContextCodeHandler(pageName) // 2. 实例化 Kuikly 委托者 kuiklyRenderViewDelegator = contextCodeHandler.initContextHandler() // 3. 找到布局中用于承载 Kuikly 的容器 View（hr_container） hrContainerView = findViewById(R.id.hr_container) // 4. 打开 Kuikly 页面：contextCode 传 ""，pageName 为页面名，pageData 为参数 contextCodeHandler.openPage(this, hrContainerView, pageName, createPageData()) } // 5~7. 在 onResume/onPause/onDestroy 中分别转发 // onResume() -> delegator.onResume() // onPause() -> delegator.onPause() // onDestroy()-> delegator.onDetach()

完整可运行实现可参考示例工程源码：KuiklyRenderActivity.kt 与 ContextCodeHandler.kt。

方式 B：View 粒度接入（混合场景）

如果需要在一个原生 Activity/Fragment 中嵌入一个或多个 Kuikly 子视图（如瀑布流卡片、Banner 混合流），可以直接使用KuiklyBaseView：

val delegate = object : KuiklyRenderViewBaseDelegatorDelegate { /* ... */ } kuiklyView = KuiklyBaseView(this, delegate) kuiklyView?.onAttach("", "yourPageName", mapOf()) // 加载 Kuikly 页面 rootView.addView(kuiklyView)

💡 卡片式瀑布流混合示例（每个 ViewHolder 中各嵌入一个 KuiklyBaseView）见 NativeAppWaterfallActivity.kt 与 NativeMixKuiklyViewDemoActivity.kt；官方文档 docs/QuickStart/android.md 中有更完整的说明。

五、实现必选适配器：图片、日志、路由、线程四件套

Kuikly 为了灵活与可扩展，不内置图片下载、日志、路由等能力，而是通过适配器（Adapter）模式委托给宿主 App 实现。共提供 9 类适配器，接入优先级如下：

各适配器的可运行示例都放在示例工程的 adapter 目录下，直接对照改写即可：

• 图片：KRImageAdapter.kt
• 日志：KRLogAdapter.kt
• 路由：KRRouterAdapter.kt
• 线程：KRThreadAdapter.kt
• 异常：KRUncaughtExceptionHandlerAdapter.kt

实现完成后，通过KuiklyRenderAdapterManager统一注入：

with(KuiklyRenderAdapterManager) { krImageAdapter = KRImageAdapter krLogAdapter = KRLogAdapter krUncaughtExceptionHandlerAdapter = KRExceptionAdapter krRouterAdapter = KRRouterAdapter krThreadAdapter = KRThreadAdapter() }

📌 两个实用细节：

1. 图片适配器的fetchDrawable可能在非 UI 线程被调用，注意线程安全；
2. 使用 Compose 场景时，建议在KRThreadAdapter的stackSize()返回8 * 1024 * 1024（8MB），避免布局嵌套过深导致StackOverflowException。

六、编写 TestPage 验证集成是否成功

平台侧接入完成后，回到 KMP 工程的shared模块，新建一个最小的测试页面：

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

然后在合适的时机跳转到容器，指定pageName为test：

KuiklyRenderActivity.start(context, "test", JSONObject())

运行后看到绿色的 "Hello Kuikly" 字样，就说明Kuikly Android 接入已成功 🎉。

七、把 Kuikly 业务代码集成到现有工程

业务代码写好之后，在KMP 业务工程中执行：

./gradlew :shared:bundleDebugAar

产物位于shared/build/output/aar，可选择远程依赖（发布到 Maven）或本地依赖集成到现有工程。

🔥aar 本地开发模式（强烈推荐）：在宿主工程settings.gradle中配置后，把 Kuikly 业务工程以源码形式引入宿主，在宿主工程中直接改 Kuikly 代码、即时编译验证，无需反复打 AAR。只需在宿主工程local.properties中添加本地业务工程路径：

kuikly.biz.dir=/path/to/kuikly-business-project

完整配置步骤见 docs/DevGuide/android-dev.md。

八、收尾配置：AndroidManifest、混淆与键盘

1. AndroidManifest.xml：为承载容器 Activity 添加：

<activity android:name=".KuiklyRenderActivity" android:windowSoftInputMode="stateUnspecified|adjustNothing" />

• stateUnspecified：避免输入框默认抢焦点，让 Kuikly 页面自控焦点；
• adjustNothing：键盘弹起时不压缩 Activity 布局，Kuikly 可通过keyboardHeightChange事件实现更精确的键盘规避。

2. 混淆规则：core-render-android已内置consumer-rules.pro，引入依赖时自动生效，一般无需手动配置；如开启 R8 仍出现类被混淆问题，可参考 core-render-android/consumer-rules.pro 补充保留规则。

3. Compose 混合场景：若 Android 上同时使用 Kuikly Compose 与原生 Jetpack Compose，需参考 docs/Compose/faq.md 配置enableConsumeSnapshot，避免状态丢失或 ANR。纯 Kuikly Compose 项目保持默认即可。

九、调试与性能排查技巧

Kuikly 业务代码就是普通 Kotlin 代码，在 Android Studio 中可以直接断点调试（KMP 工程运行androidApp即可）：

排查启动性能时，用 AS 的 Profiler（Method Trace）观察消息队列线程——其中HRContextQueueHandlerThread 就是 Kuikly 线程，可以看到页面创建过程中执行了哪些任务、是否有耗时操作：

常见启动慢的原因：created中同步等待网络请求、首屏拉取数据过多、同步 Module 调用耗时过长等，系统性的分析思路可参考 docs/DevGuide/android-start-guide.md。

常见问题 FAQ

Q1：页面打开白屏 / 报兼容性问题？90% 是版本不一致——请核对 KMP 工程与宿主工程的 Kuikly 版本号（core、core-render-android、KMP 侧）三者完全相同。

Q2：Image 组件图片不显示？图片加载适配器是必须实现的，检查KuiklyRenderAdapterManager.krImageAdapter是否已设置，且fetchDrawable实现正确。

Q3：View 方式接入后页面不刷新？View 方式的生命周期需要手动转发：在宿主onResume/onPause/onDestroy中分别调用kuiklyView.onResume()/onPause()/onDetach()，漏掉任一都会导致状态异常。

Q4：传参pageData要自己包一层param吗？不需要。直接传扁平的Map<String, Any>或JSONObject，框架内部会自动包裹。

Q5：Kuikly 线程是什么，任务会卡死 App 吗？Kuikly 复用宿主提供的子线程执行任务（由线程适配器决定），不会自行创建线程；若业务在生命周期回调中做了耗时同步操作，才会阻塞页面创建，这是接入后最需要自查的一点。

按照以上 6 个步骤完成Kuikly Android 接入后，你的现有 Android 工程就拥有了运行跨端页面的能力——同一份 Kotlin 页面代码，稍作壳工程配置即可平移到 iOS 与鸿蒙。更多组件 API 可查阅 docs/API/，开发进阶内容见 docs/DevGuide/。

【免费下载链接】KuiklyUI基于KMP技术的高性能、全平台开发框架，具备统一代码库、极致易用性和动态灵活性。 Provide a high-performance, full-platform development framework with unified codebase, ultimate ease of use, and dynamic flexibility. 注意：本仓库为Github仓库镜像，PR或Issue请移步至Github发起，感谢支持！项目地址: https://gitcode.com/Tencent-TDS/KuiklyUI