核心内容摘要
9.1人网站与张津瑜事件：流量背后，是道德的拷问还是人性的沉沦？
【开源鸿蒙跨平台开发–KuiklyUI–03】KuiklyUI 入门实战从零打造高性能跨平台 Todo 应用
什么是 KuiklyUIKuiklyUI是腾讯开源的一款基于Kotlin Multiplatform (KMP)的高性能跨平台 UI 框架。
它的核心理念是“Write Once, Run Everywhere”但与 Flutter 或 React Native 不同KuiklyUI 更加强调原生性能和轻量级。
核心优势极致性能核心逻辑编译为 Native 二进制 (Android/iOS/HarmonyOS)UI 渲染直接驱动平台原生组件 (View/UIKit/ArkUI)。
原生体验拒绝自绘引擎带来的非原生手感KuiklyUI 的组件就是原生组件。
双 DSL 支持支持自研的简洁 DSL 和 Jetpack Compose 风格 DSL。
全平台覆盖Android, iOS, HarmonyOS Next, Web (H
, 小程序。
环境准备在开始之前请确保你的开发环境满足以下要求JDK: JDK 17 (推荐 JDK
17.
6 或更高)Android 开发: Android Studio Ladybug 或更高版本 (支持 KMP 插件)鸿蒙开发: DevEco Studio
0 (用于运行鸿蒙宿主工程)构建工具: Gradle
0 (项目内置无需手动安装)操作系统: Windows / macOS / Linux
1 鸿蒙环境特别配置对于鸿蒙开发你需要配置鸿蒙 SDK 的环境变量以便 Gradle 能够找到它Windows: 设置系统环境变量DEVECO_SDK_HOME指向你的 DevEco SDK 路径例如C:\Users\YourName\AppData\Local\Huawei\Sdk。
macOS: 在~/.bash_profile或~/.zshrc中添加export DEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdk。
项目结构概览克隆项目后你会看到以下核心目录KuiklyUI/ ├── core/ # 框架核心 (KMP) ├── compose/ # Compose DSL 适配层 ├── demo/ # 演示代码 (我们将在这里编写业务逻辑) │ └── src/commonMain/ # 跨平台通用代码 (Write Code Here!) │ ├── kotlin/com/tencent/kuikly/demo/ │ │ ├── pages/ # 页面目录 │ │ ├── widgets/ # 公共组件目录 │ │ └── App.kt # 应用入口 ├── androidApp/ # Android 宿主工程 (仅包含启动代码) ├── ohosApp/ # HarmonyOS 宿主工程 (仅包含启动代码) ├── iosApp/ # iOS 宿主工程 └──
0_ohos_demo_build.bat # 鸿蒙编译脚本 (Windows)开发理念我们的绝大部分代码95%以上都编写在demo/src/commonMain目录下各个平台的App目录仅作为宿主壳工程负责加载 Kuikly 引擎。
从AtomGit上下载这个项目KuiklyTodo解压存放代码的地方查看项目代码本项目是基于模板项目修改的
实战开发一个 Todo 应用我们将实现一个功能完善的待办事项应用包含待办事项列表展示添加新事项标记完成/未完成删除事项
1 定义数据模型首先我们需要一个数据类来描述待办事项。
在demo/src/commonMain/kotlin/com/tencent/kuikly/demo/pages/todo目录下创建TodoItem.ktpackagecom.tencent.kuikly.demo.pages.tododataclassTodoItem(valid:Long,varcontent:String,varisCompleted:Booleanfalse)
2 创建页面逻辑类 (ViewModel)在同目录下创建TodoPage.kt。
这是页面的大脑负责状态管理和业务逻辑。
/** * ProjectName : KuiklyUI * Author : GuoJiaHui * Time : 2026年01月29日 17:30 PM * Description : 待办事项页面逻辑控制器 * 负责管理待办事项列表的数据状态、增删改查操作 */packagecom.tencent.kuikly.demo.pages.todoimportcom.tencent.kuikly.core.annotations.Pageimportcom.tencent.kuikly.core.base.ViewBuilderimportcom.tencent.kuikly.demo.pages.base.BasePagerimportcom.tencent.kuikly.core.reactive.handler.observableimportcom.tencent.kuikly.core.reactive.handler.observableList/** * 待办事项页面类 * 使用 Page 注解标记为页面路由名称为 todo_page */Page(todo_page)internalclassTodoPage:BasePager(){/** 待办事项列表数据使用 observableList 实现响应式更新 */vartodoListbyobservableListTodoItem()/** 输入框文本状态使用 observable 实现双向绑定 */varinputTextbyobservable()/** * 页面创建生命周期回调 * 在此初始化数据 */overridefuncreated(){super.created()// 初始化演示数据initData()}/** * 初始化演示数据 * 添加默认的待办事项 */privatefuninitData(){todoList.add(TodoItem(1,学习 KuiklyUI 框架))todoList.add(TodoItem(2,创建一个 Todo 应用))}/** * 构建页面 UI 结构 * return ViewBuilder UI 构建函数 */overridefunbody():ViewBuilder{returnbuildTodoUI(this)}/** 生成 ID 的计数器起始值为 100 */privatevarnextId100L/** * 添加新的待办事项 * 校验输入是否为空创建新项并添加到列表最后清空输入框 */funaddTodo(){if(inputText.isBlank())returnvalnewItemTodoItem(nextId,inputText)todoList.add(newItem)inputText}/** * 切换待办事项的完成状态 * param item 目标待办事项对象 */funtoggleTodo(item:TodoItem){item.isCompleted!item.isCompleted// 触发列表更新通过重新赋值触发 observableList 的更新机制valindextodoList.indexOf(item)if(index
{todoList[index]item}}/** * 删除指定的待办事项 * param item 要删除的待办事项对象 */fundeleteTodo(item:TodoItem){todoList.remove(item)}/** * 清除所有已完成的待办事项 * 遍历列表并移除 isCompleted 为 true 的项 */funclearCompleted(){todoList.removeAll{it.isCompleted}}}
3 编写声明式 UI创建TodoPageUI.kt使用 Kuikly 自研 DSL 描述界面。
这里的写法类似 Flutter 或 SwiftUI但完全基于 Kotlin。
/** * ProjectName : KuiklyUI * Author : GuoJiaHui * Time : 2026年01月29日 17:30 PM * Description : 待办事项页面UI构建逻辑 * 包含整体布局、样式定义及事件绑定 */packagecom.tencent.kuikly.demo.pages.todoimportcom.tencent.kuikly.core.base.Colorimportcom.tencent.kuikly.core.base.ViewBuilderimportcom.tencent.kuikly.core.pager.Pagerimportcom.tencent.kuikly.core.views.*importcom.tencent.kuikly.core.directives.vforimportcom.tencent.kuikly.core.directives.vifimportcom.tencent.kuikly.core.base.Borderimportcom.tencent.kuikly.core.base.BorderStyleimportcom.tencent.kuikly.core.base.BoxShadow/** * 构建 Todo 页面的 UI 结构 * param page 页面上下文对象需转换为 TodoPage 类型以访问数据 * return ViewBuilder UI 构建闭包 */funbuildTodoUI(page:Pager):ViewBuilder{valctxpageasTodoPagereturn{View{attr{// 设置页面主容器充满全屏flex(1f)backgroundColor(Color.WHITE)// 处理安全区域内边距适配刘海屏/动态岛padding(top16fctx.pageData.safeAreaInsets.top,left16fctx.pageData.safeAreaInsets.left,right16fctx.pageData.safeAreaInsets.right,bottom16fctx.pageData.safeAreaInsets.bottom)}// 标题栏组件Text{attr{text(待办事项清单)fontSize(24f)fontWeightBold()marginBottom(20f)color(Color.BLACK)}}// 顶部输入区域容器View{attr{flexDirectionRow()// 水平布局marginBottom(20f)height(50f)alignItemsCenter()// 垂直居中}// 文本输入框组件Input{attr{flex(1f)// 占据剩余宽度text(ctx.inputText)// 绑定输入文本placeholder(需要做什么)fontSize(16f)backgroundColor(Color(0xFFF5F5F
)borderRadius(8f)height(44f)}event{// 监听文本变化事件更新数据模型textDidChange{params-ctx.inputTextparams.text}}}// 添加按钮组件View{attr{width(80f)height(44f)marginLeft(10f)backgroundColor(Color(0xFF007AFF))borderRadius(8f)justifyContentCenter()// 内容居中alignItemsCenter()// 增加按钮投影效果boxShadow(BoxShadow(0f,2f,4f,Color(0x40007AFF)))}Text{attr{text(添加)color(Color.WHITE)fontWeightBold()fontSize(16f)}}event{// 绑定点击事件调用添加逻辑click{ctx.addTodo()}}}}// 列表显示区域View{attr{flex(1f)// 占据剩余空间}// 空状态提示当列表为空时显示vif({ctx.todoList.isEmpty()}){View{attr{flex(1f)justifyContentCenter()alignItemsCenter()}Text{attr{text(暂无待办事项)fontSize(18f)color(Color(0xFF
)marginBottom(8f)}}Text{attr{text(快去添加一个吧)fontSize(14f)color(Color(0xFFCCCCCC))}}}}// 列表渲染循环遍历 todoList 生成列表项vfor({ctx.todoList}){item-View{attr{flexDirectionColumn()}// 列表项内容行View{attr{flexDirectionRow()alignItemsCenter()padding(top12f,bottom12f)}// 复选框组件自定义 View 模拟View{attr{width(24f)height(24f)borderRadius(12f)// 根据完成状态设置边框和背景色border(Border(2f,BorderStyle.SOLID,if(item.isCompleted)Color(0xFF007AFF)elseColor(0xFFCCCCCC)))backgroundColor(if(item.isCompleted)Color(0xFF007AFF)elseColor.TRANSPARENT)marginRight(12f)justifyContentCenter()alignItemsCenter()}event{// 点击复选框切换状态click{ctx.toggleTodo(item)}}// 勾选图标Text{attr{text(✓)color(Color.WHITE)fontSize(14f)fontWeightBold()// 控制勾选标记的透明度opacity(if(item.isCompleted)1felse0f)}}}// 待办事项文本内容Text{attr{text(item.content)fontSize(16f)// 完成状态文字颜色变浅color(if(item.isCompleted)Color(0xFF
elseColor(0xFF
)flex(1f)// 完成状态添加删除线if(item.isCompleted)textDecorationLineThrough()elsetextDecorationwithnone}event{// 点击文字也可切换状态click{ctx.toggleTodo(item)}}}// 删除按钮View{attr{padding(8f)// 增加点击热区}event{click{ctx.deleteTodo(item)}}Text{attr{text(✕)color(Color(0xFFFF3B
)// 红色警示色fontSize(18f)}}}}// 分割线View{attr{height(1f)backgroundColor(Color(0xFFEEEEEE))marginLeft(36f)// 缩进以对齐文本}}}}}// 底部状态栏与操作区仅当列表不为空时显示vif({ctx.todoList.isNotEmpty()}){View{attr{flexDirectionColumn()}// 顶部分割线View{attr{height(1f)backgroundColor(Color(0xFFEEEEEE))}}// 底部内容容器View{attr{flexDirectionRow()justifyContentSpaceBetween()// 两端对齐alignItemsCenter()padding(top16f)}// 剩余待办计数Text{attr{text(${ctx.todoList.count{!it.isCompleted}}项待办)fontSize(14f)color(Color(0xFF
)}}// 清除已完成按钮View{attr{padding(8f)}event{click{ctx.clearCompleted()}}Text{attr{text(清除已完成)fontSize(14f)color(Color(0xFF007AFF))}}}}}}}}}
跨端运行指南
1 Android 运行Android 是最简单的运行平台。
打开 Android Studio。
等待 Gradle Sync 完成。
在运行配置下拉菜单中选择androidApp。
点击运行按钮 (Run)。
修改完代码后要先重新构建构建完成后点击最上面的运行安卓运行效果提示如果遇到 KMP 相关的配置错误请确保你的 Android Studio 安装了 Kotlin Multiplatform Mobile 插件。
2 HarmonyOS 运行鸿蒙的运行流程涉及 Native 库的交叉编译需要特别注意。
步骤 1编译 Native 库KuiklyUI 的核心逻辑需要编译成鸿蒙系统的动态链接库 (.so)。
找到项目根目录下的
0_ohos_demo_build.bat文件。
双击运行或者在终端中执行.\
0_ohos_demo_build.bat脚本会自动执行 Gradle 任务编译生成libshared.so并复制到ohosApp/entry/libs/arm64-v8a/目录下。
注意如果脚本报错找不到 SDK请检查章节
1 中的环境变量配置。
步骤 2配置 DevEco Studio启动 DevEco Studio。
选择Open Project打开项目中的ohosApp目录。
等待 Sync 完成。
步骤 3实现 Native Bridge (可选但推荐)如果你的应用需要跳转页面或调用原生能力需要配置 Bridge。
打开ohosApp/entry/src/main/ets/kuikly/modules/KRBridgeModule.ets完善openPage方法// KRBridgeModule.etsimportrouterfromohos.router;// ...// TODO open new pageprivateopenPage(params:KRAny){console.info(KRBridgeModule: openPage method execution started);try{letargs:Recordstring,Object;if(typeofparamsstring){argsJSON.parse(params)asRecordstring,Object;}else{argsparamsasRecordstring,Object;}consturlargs[url]asstring;// 使用鸿蒙原生路由跳转router.pushUrl({url:pages/Index,params:{pageName:url// 将目标页面名传给 Index 页面}});}catch(e){console.error(KRBridgeModule: openPage error:${JSON.stringify(e)});}}步骤 4真机运行由于 Kuikly 编译的是 ARM64 架构的.so库不支持 x86 模拟器。
连接你的鸿蒙真机 (Mate 60 / Pura 70 等)。
或者申请华为云真机(参考我们另一篇云真机部署教程)。
点击 DevEco Studio 的运行按钮。
真机运行效果
调试技巧与
常见问题
1 如何查看日志Android: 使用 Logcat过滤Kuikly或System.out。
HarmonyOS: 使用 DevEco Studio 的 Log 面板过滤HiLog关键字Kuikly或KRBridgeModule。
在 Kotlin 代码中可以使用KLog.i(Tag, Message)打日志。
2 常见编译错误Unresolved reference: System:原因: Kotlin/Native (鸿蒙/iOS) 中没有 Java 的System类。
解决: 使用Clock.System.now()(需要 kotlinx-datetime) 或者简单的自增 ID (如本教程所示)。
settings.
2.
ohos.gradle.kts does not exist:原因: 缺少鸿蒙专用构建配置。
解决: 运行.bat脚本前确保该文件存在 (脚本通常会自动处理或依赖项目预设)。
7.
总结通过这个实战我们不仅完成了一个 Todo 应用还深入理解了MVI 架构雏形State (状态) - UI (视图) - Event (事件) 的单向数据流。
DSL 布局如何用 Kotlin 代码构建复杂的 Flexbox 布局。
多端适配如何通过一套代码在 Android 和 HarmonyOS 上运行原生的 UI。
KuiklyUI让跨平台开发不再是 WebView 的妥协而是原生性能的释放。
快去尝试构建更复杂的应用吧