Kuikly 框架架构与目录导览（HarmonyOS 视角）

本文从 KuiklyUI 源码仓库结构 出发，解释 Kuikly 的整体架构、每个关键目录的职责，并给出 鸿蒙开发只需关注的目录清单，便于快速进入开发状态。

先跟大家说个好消息，该框架已经解决了windows平台的快速编译鸿蒙产物（也就是说win用户可以像mac用户一样只需一下两步就可以编译ohos产物了：

1. 配置环境变量 OHOS_SDK_HOME，指向鸿蒙 SDK 路径：
   变量名: OHOS_SDK_HOME
   路径: %TOOL_HOME%\sdk
   变量名: TOOL_HOME
   路径: D:\DevEcoStudio
   注意："D:\DevEcoStudio"中D盘为示例演示，实则除C盘以外任何盘都可以
2. 在KuiklyUI根目录执行 Windows 编译脚本：
   2.0_ohos_demo_build.bat

1. Kuikly 架构拆解

1.1 Kuikly 的核心思路

Kuikly 基于 Kotlin Multiplatform，用跨端逻辑 + 抽象 UI 渲染接口的方式实现 UI 跨平台，同时复用平台原生组件，实现轻量、高性能与可动态化的目标。KuiklyUI/docs/Introduction/arch.md

1.2 KuiklyUI 与 KuiklyBase

官方架构描述中，Kuikly 主要分为两块：KuiklyUI/docs/Introduction/arch.md

• KuiklyUI ：框架主体，包含 Core 与 Render 两个层面。
  • Core：提供跨端高级组件、动画、手势、布局与统一 API；同时支持 Compose DSL 与自研 DSL。KuiklyUI/docs/Introduction/arch.md
  • Render：按平台实现渲染层，覆盖 Android、iOS、macOS、HarmonyOS、H5/小程序等。KuiklyUI/docs/Introduction/arch.md
• KuiklyBase：跨端基础设施层，偏逻辑与工具链能力（协程、多线程、工具链等），用于支撑完整跨端 App 能力。KuiklyUI/docs/Introduction/arch.md

1.3 渲染链路（从页面到平台）

在 KuiklyUI 内部，UI 运行链路可以理解为：

业务页面 / DSL / Compose
        ↓
Core（组件/布局/事件/Bridge）
        ↓
Render（平台渲染层）
        ↓
宿主 App（Android/iOS/HarmonyOS...）

该结构也是目录划分的核心逻辑：跨端能力在 core/ 与 compose/ ，平台实现分别落在 core-render-* 目录和各平台宿主工程内。KuiklyUI/README-zh_CN.md

---

2. 目录结构与职责

以下内容基于 KuiklyUI 根目录结构与官方说明整理：KuiklyUI/README-zh_CN.md

2.1 框架目录图（顶层简化版）

这张目录图只保留框架与平台相关的核心层级，方便快速定位职责：

KuiklyUI/
├── core/                 # 跨端核心：组件/布局/事件/Bridge
├── compose/              # Compose DSL 跨端实现
├── core-render-android/  # Android 渲染层
├── core-render-ios/      # iOS 渲染层
├── core-render-ohos/     # HarmonyOS 渲染层
├── core-render-web/      # Web 渲染层
├── core-annotations/     # 注解定义（如 @Page）
├── core-ksp/             # 注解处理与入口生成
├── demo/                 # DSL 示例工程（跨端业务代码）
├── androidApp/           # Android 宿主壳工程
├── iosApp/               # iOS 宿主壳工程
├── macApp/               # macOS 宿主壳工程
├── h5App/                # H5 宿主壳工程
├── miniApp/              # 小程序宿主壳工程
├── ohosApp/              # HarmonyOS 宿主壳工程
├── buildSrc/             # 构建脚本与打包逻辑
└── docs/                 # 文档与教程

目录图的核心阅读方式是：跨端能力集中在 core/ 与 compose/，平台差异在 core-render-*，而最终运行入口在各平台宿主工程（如 ohosApp/）。这也解释了 Kuikly 的"同一套业务代码 + 多端渲染 + 平台壳工程"的结构设计。

目录	主要职责	何时会改动
core/	跨平台核心模块：UI、布局、Bridge 等核心能力	框架级功能/组件/布局问题排查
compose/	Compose DSL 跨端实现（源码来自 Compose Multiplatform 并做过适配）	使用 Compose DSL 或维护 Compose 适配
core-render-android/ core-render-ios/ core-render-ohos/ core-render-web/	各平台渲染实现	需要改动平台渲染层或平台适配时
core-annotations/	注解定义（如 @Page）	添加/扩展 DSL 注解能力
core-ksp/	KSP 注解处理，生成入口	调整代码生成逻辑
buildSrc/	构建脚本与打包逻辑	需要改构建流程、产物结构时
demo/	DSL 示例工程（跨端业务代码）	写页面、写业务逻辑、验证组件
androidApp/ iosApp/ macApp/ miniApp/ h5App/ ohosApp/	各平台宿主工程（壳工程）	平台侧集成、资源、原生模块接入
docs/	框架文档与教程	更新文档内容

关于 compose/：该目录基于 Compose Multiplatform 1.7.3 做过适配与包名调整，避免与官方 Compose 冲突。KuiklyUI/README-zh_CN.md

---

3. 鸿蒙开发：只需关注的目录

如果你只做 HarmonyOS 业务开发，通常只需要关注以下几块（从"日常必看"到"按需深入"）：

3.1 日常必看

1. demo/ ：跨端业务页面与模块示例。页面通常位于 demo/src/commonMain/...，例如相机页面 CameraTestPage。

KuiklyUI/demo/src/commonMain/kotlin/com/tencent/kuikly/demo/pages/CameraTestPage.kt

2. ohosApp/ ：鸿蒙宿主工程。这里负责启动、资源与原生模块注册。例如模块注册集中在 KuiklyViewDelegate.ets。

KuiklyUI/ohosApp/entry/src/main/ets/kuikly/KuiklyViewDelegate.ets

3. core-render-ohos/：鸿蒙渲染层实现，平台适配、渲染细节都在这里。

这里是引用

KuiklyUI/README-zh_CN.md

5. 鸿蒙构建脚本与配置：

• Mac用户：鸿蒙 demo 构建脚本是 2.0_ohos_demo_build.sh，配套的设置在 settings.2.0.ohos.gradle.kts 等文件中。
• win用户：鸿蒙demo构建脚本是2.0_ohos_demo_build.bat，配套的设置在 settings.2.0.ohos.gradle.kts 等文件中。
  win用户需要配置的环境变量：（这个环境变量跟flutter编译鸿蒙产物的配置一致的）
  

3.2 按需深入

• core/：当你需要扩展组件、布局、事件或桥接能力时。
• compose/：如果团队使用 Compose DSL，或需要修改 Compose 适配逻辑。KuiklyUI/README-zh_CN.md
• core-annotations/ + core-ksp/ ：扩展或修改 @Page 等注解能力时。

3.3 通常可忽略

• 其他平台宿主工程（androidApp/、iosApp/、macApp/、h5App/、miniApp/）
• 发布脚本、打包工具链（除非你需要自定义构建流程）

---

4. 总结：鸿蒙开发最小关注集

最小关注集可以记为：

demo/ + ohosApp/ + core-render-ohos/ + 鸿蒙构建脚本

剩余目录只有在修改框架能力或支持其他平台时再深入即可。

5. 文档地址

项目地址：https://atomgit.com/Tencent-TDS/KuiklyUI
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net