KuiklyUI for OpenHarmony 实战 02：Kuikly 工程创建与鸿蒙运行（Mac）

摘要

本文记录在 macOS 环境下完成 Android Studio 安装初始化、Android SDK 配置、Kuikly 工程创建、Ohos 工程加载、页面代码编写 ，并在 鸿蒙真机与模拟器 上运行验证的完整实践过程。

在完成 KuiklyUI 源码构建与示例工程运行验证后，本文以 新建 Kuikly 工程 为起点，覆盖从开发环境准备、跨端工程加载，到 页面级代码修改与工程代码推送至 AtomGit 公开仓库 的完整流程。

一、Android Studio 安装与初始化

1.1 下载 Android Studio

通过官方页面下载 macOS 版本 Android Studio：

text 复制代码

https://developer.android.com/studio

下载完成后获得 AndroidStudio.dmg 安装文件。

图 1-1 Android Studio 官方下载页面

1.2 安装 Android Studio

双击 AndroidStudio.dmg，将 Android Studio 图标拖拽至 Applications 目录。

图 1-2 Android Studio 拖拽安装界面

1.3 启动 Android Studio

在 Applications 目录中启动 Android Studio，进入欢迎界面。

图 1-3 Android Studio 欢迎界面

1.4 完成初始配置

在初始化向导中选择默认选项，完成以下配置流程：

SDK 组件初始化
模拟器基础组件准备
Gradle 环境初始化

配置完成后进入 Android Studio 主界面。

图 1-4 Android Studio 初始配置完成

1.5 设置 Gradle JDK

进入设置页面：

text 复制代码

Android Studio → Settings → Build, Execution, Deployment → Build Tools → Gradle

将 Gradle JDK 设置为 JDK 17。

图 1-5 Gradle JDK 配置为 JDK 17

1.6 配置 Android SDK Location

进入 Android SDK 配置页面：

text 复制代码

Android Studio → Settings → Languages & Frameworks → Android SDK

将 Android SDK Location 设置为：

text 复制代码

/Users/<用户名>/Library/Android/sdk

确认以下组件已安装：

Android SDK Platform
Android SDK Build-Tools
Android Emulator
Android SDK Platform-Tools

图 1-6 Android SDK Location 与组件配置完成

1.7 安装 Kuikly 相关插件

进入插件管理页面：

text 复制代码

Android Studio → Settings → Plugins → Marketplace

安装以下插件：

Kotlin Multiplatform Mobile
Kuikly Android Studio Plugin（版本 ≥ 1.1.0）

安装完成后重启 Android Studio。

图 1-7 Kuikly 插件安装完成

1.8 安装与配置 CocoaPods

Kuikly iOS 侧依赖 CocoaPods 管理原生依赖。

安装 Homebrew：

bash 复制代码

sudo rm -rf /opt/homebrew
sudo mkdir -p /opt/homebrew
sudo chown -R "$(whoami)":admin /opt/homebrew
git clone --depth=1 https://github.com/Homebrew/brew /opt/homebrew
eval "$(/opt/homebrew/bin/brew shellenv)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
brew --version

图 1-8 Homebrew 安装完成

安装 CocoaPods：

bash 复制代码

brew install cocoapods
pod --version

图 1-9 CocoaPods 安装完成

1.9 配置 Git 依赖拉取规则

检查是否存在不可用的全局 Git 重写规则：

bash 复制代码

git config --global --get-regexp '^url\..*insteadOf$'

如存在不可访问规则，先移除后再配置 Kuikly 相关仓库定向重写：

bash 复制代码

git config --global url."https://atomgit.com/Tencent-TDS/KuiklyUI.git".insteadOf https://github.com/Tencent-TDS/KuiklyUI.git
git config --global url."https://gitee.com/mirrors/SDWebImage.git".insteadOf https://github.com/SDWebImage/SDWebImage.git

二、Kuikly 工程创建

2.1 创建 Kuikly 工程

在 Android Studio 中进入新建工程流程：

text 复制代码

Projects → New Project

在模板列表中选择 Kuikly Project Template。

图 2-1 选择 Kuikly Project Template

2.2 配置工程信息

填写以下信息：

Project Name
Package Name
Project Location

完成后点击创建，等待工程初始化完成。

图 2-2 Kuikly 工程基础信息配置

2.3 初始化 iOS 依赖

进入 iosApp 目录执行 Pods 安装：

bash 复制代码

cd /Users/<用户名>/AndroidStudioProjects/<ProjectName>/iosApp
rm -rf Pods Podfile.lock
pod install

安装完成后生成 Pods 目录与 *.xcworkspace 文件。

图 2-3 pod install 完成日志

三、使用 DevEco Studio 加载 Ohos 工程

3.1 打开 ohosApp 工程

启动 DevEco Studio，选择打开工程并指定路径：

text 复制代码

<Kuikly 工程目录>/ohosApp

3.2 执行工程同步

工程打开后，DevEco Studio 自动执行：

hvigor 配置解析
模块依赖加载
OpenHarmony SDK 校验

同步完成后工程进入可运行状态。

图 3-1 ohosApp 工程同步完成

3.3 hvigor 任务模型说明（关键）

在 ohosApp 根目录执行：

bash 复制代码

hvigorw tasks

可观察到以下特征：

不存在 build、assembleDebug 等 Gradle 任务
构建统一由 kuikly_build 驱动
shared 模块的 Kotlin/Native 编译由 Kuikly 插件接管

图 3-2 hvigor tasks 列表

四、运行鸿蒙 App（真机与模拟器）

4.1 真机运行

完成以下准备后运行真机：

鸿蒙设备开启开发者模式
设备已通过 USB 或 hdc 连接
ohosApp 工程完成签名配置

在 DevEco Studio 中选择真机并执行运行。

图 4-1 Kuikly App 真机运行效果

4.2 模拟器运行

在未连接真实设备的情况下，直接选择鸿蒙模拟器运行。

模拟器运行具备以下特性：

不依赖 hdc 无线调试
不依赖真实设备签名
构建流程与真机一致

图 4-2 Kuikly App 模拟器运行效果

五、编写 Kuikly 页面代码（OpenHarmony）

5.1 新建页面文件

在 shared 模块中新建页面文件：

text 复制代码

shared/src/commonMain/kotlin/<package>/pages/HelloWorldPage.kt

图 5-1 新建 HelloWorldPage 文件

5.2 HelloWorldPage 实现

kotlin 复制代码

package com.soraluna.helloworld.pages

import com.tencent.kuikly.core.annotations.Page
import com.tencent.kuikly.core.base.*
import com.tencent.kuikly.core.views.*
import com.soraluna.helloworld.base.BasePager

@Page("HelloWorld")
internal class HelloWorldPage : BasePager() {

    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            Text {
                attr {
                    text("Hello Kuikly")
                    fontSize(14f)
                }
            }
        }
    }
}

图 5-2 HelloWorldPage 页面代码

5.3 页面运行验证

运行 ohosApp 后，在路由入口输入：

text 复制代码

HelloWorld

页面成功加载并显示文本内容。

图 5-3 HelloWorld 页面运行效果

六、实践小结

Kuikly 新工程在 OpenHarmony 平台完成创建与运行
ohosApp 是唯一合法的 hvigor 构建入口
shared 模块的 Native 编译由 Kuikly 插件统一接管
模拟器与真机运行流程一致但依赖条件不同
页面需实现 IPager 与 onCreatePager 才能参与路由