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

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 是基于 KMPKotlin 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 / callKotlinKotlin 与原生之间的双向调用通道配合 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版本) // 核心库 }⚠️两个关键注意点core-render-android与core的版本号必须和 KMP 跨端工程使用的 Kuikly 版本完全一致否则会出现兼容性问题最新版本号可在 docs/ChangeLog/changelog.md 查看2.5.0 版本后需要添加 maven 源maven(https://mirrors.tencent.com/repository/maven-tencent/)。渲染器模块的源码位于 core-render-android/它会把 Kuikly 的 UI 树翻译成 Android 原生 ViewKRView、KRListView、KRScrollView 等。四、实现承载容器Activity 与 View 两种接入方式方式 AActivity 接入整页场景最常用新建一个KuiklyRenderActivity作为 Kuikly 页面的承载容器核心流程是创建处理器 → 实例化 Delegator → 打开页面 → 转发生命周期四步override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // 1. 创建页面打开的封装处理器pageName 从 Intent 中读取 contextCodeHandler ContextCodeHandler(pageName) // 2. 实例化 Kuikly 委托者 kuiklyRenderViewDelegator contextCodeHandler.initContextHandler() // 3. 找到布局中用于承载 Kuikly 的容器 Viewhr_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。方式 BView 粒度接入混合场景如果需要在一个原生 Activity/Fragment 中嵌入一个或多个 Kuikly 子视图如瀑布流卡片、Banner 混合流可以直接使用KuiklyBaseViewval delegate object : KuiklyRenderViewBaseDelegatorDelegate { /* ... */ } kuiklyView KuiklyBaseView(this, delegate) kuiklyView?.onAttach(, yourPageName, mapOf()) // 加载 Kuikly 页面 rootView.addView(kuiklyView)对比项Activity 方式View 方式容器Delegator 管理KuiklyBaseView继承 FrameLayout生命周期由 Delegator 自动管理需手动调用onResume/onPause/onDetach尺寸自动撑满通过LayoutParams自行指定代理协议KuiklyRenderViewBaseDelegatorDelegate相同能力一致 卡片式瀑布流混合示例每个 ViewHolder 中各嵌入一个 KuiklyBaseView见 NativeAppWaterfallActivity.kt 与 NativeMixKuiklyViewDemoActivity.kt官方文档 docs/QuickStart/android.md 中有更完整的说明。五、实现必选适配器图片、日志、路由、线程四件套Kuikly 为了灵活与可扩展不内置图片下载、日志、路由等能力而是通过适配器Adapter模式委托给宿主 App 实现。共提供 9 类适配器接入优先级如下适配器作用是否必须图片加载适配器为 Image 组件提供下载解码能力✅ 必须日志适配器框架与业务的日志输出✅ 必须页面路由适配器Kuikly 页面间跳转 / 打开新容器✅ 必须线程适配器提供子线程Kuikly 不自行建线程✅ 必须异常适配器业务异常的统一处理推荐颜色转换 / 自定义字体 / APNG / PAG按需扩展能力按需各适配器的可运行示例都放在示例工程的 adapter 目录下直接对照改写即可图片KRImageAdapter.kt日志KRLogAdapter.kt路由KRRouterAdapter.kt线程KRThreadAdapter.kt异常KRUncaughtExceptionHandlerAdapter.kt实现完成后通过KuiklyRenderAdapterManager统一注入with(KuiklyRenderAdapterManager) { krImageAdapter KRImageAdapter krLogAdapter KRLogAdapter krUncaughtExceptionHandlerAdapter KRExceptionAdapter krRouterAdapter KRRouterAdapter krThreadAdapter KRThreadAdapter() } 两个实用细节图片适配器的fetchDrawable可能在非 UI 线程被调用注意线程安全使用 Compose 场景时建议在KRThreadAdapter的stackSize()返回8 * 1024 * 10248MB避免布局嵌套过深导致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为testKuiklyRenderActivity.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:windowSoftInputModestateUnspecified|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 的 ProfilerMethod Trace观察消息队列线程——其中HRContextQueueHandlerThread 就是 Kuikly 线程可以看到页面创建过程中执行了哪些任务、是否有耗时操作常见启动慢的原因created中同步等待网络请求、首屏拉取数据过多、同步 Module 调用耗时过长等系统性的分析思路可参考 docs/DevGuide/android-start-guide.md。常见问题 FAQQ1页面打开白屏 / 报兼容性问题90% 是版本不一致——请核对 KMP 工程与宿主工程的 Kuikly 版本号core、core-render-android、KMP 侧三者完全相同。Q2Image 组件图片不显示图片加载适配器是必须实现的检查KuiklyRenderAdapterManager.krImageAdapter是否已设置且fetchDrawable实现正确。Q3View 方式接入后页面不刷新View 方式的生命周期需要手动转发在宿主onResume/onPause/onDestroy中分别调用kuiklyView.onResume()/onPause()/onDetach()漏掉任一都会导致状态异常。Q4传参pageData要自己包一层param吗不需要。直接传扁平的MapString, Any或JSONObject框架内部会自动包裹。Q5Kuikly 线程是什么任务会卡死 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考