Kuikly-OH 实践（mac版本）

Kuikly 是基于 Kotlin MultiPlatform(KMP) 实现的一套跨平台应用框架，支持 Android、iOS 和 HarmonyOS 平台开发。

环境准备

1. 安装 Android Studio

下载并安装 Android Studio

重要提示： 如果你的 Android Studio 版本大于等于 2024.2.1，请将 Gradle JDK 版本切换为 JDK17（该版本默认 Gradle JDK 为 21，与项目使用的配置不兼容）

切换方式：Android Studio -> Settings -> Build,Execution,Deployment -> Build Tools -> Gradle -> Gradle JDK

2. 安装必要的插件

在 Android Studio 中安装以下插件，路径为：Settings -> Preferences -> Plugins -> Marketplace

Kotlin 插件（通常已内置）
Kotlin Multiplatform Mobile 插件
- 插件地址：https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile
Kuikly Android Studio 插件
- 插件地址：https://plugins.jetbrains.com/plugin/27076-kuiklytemplate/versions/stable
- 详细安装说明：https://kuikly.tds.qq.com/DevGuide/as-plugin.html#安装
- 注意： 若想通过插件生成 Ohos 工程，请更新插件至 1.1.0 版本以上

Kuikly Android Studio 插件功能：

新建 Kuikly 业务工程：一键生成 Kuikly 业务工程与 Android/iOS/Ohos App 宿主工程，自动集成 Kuikly 依赖等
新建 Kuikly 的 ComposeView 类：自动帮业务开发者生成组合组件的模板代码
新建 Kuikly 的 Pager 类：自动帮业务开发者生成 Pager 的模板代码

3. 安装 JDK 17

下载 JDK 17 并配置环境变量。

4. 安装 DevEco Studio（仅 Ohos 开发需要）

如需运行 Ohos，还需要安装 DevEco Studio

5. 环境检查（可选）

使用 kdoctor 工具检查开发环境配置：

bash 复制代码

kdoctor

常见环境问题：

Xcode 相关问题： 如果只开发 Android 和 Ohos，可以不安装 Xcode。如果遇到 Xcode 相关错误，请参考常见问题部分
CocoaPods 配置： 如果只开发 Android 和 Ohos，CocoaPods 不是必需的。如需 iOS 开发，请安装 CocoaPods：
bash 复制代码
```
sudo gem install cocoapods
```
安装后，在 ~/.zprofile 中添加 UTF-8 编码配置：
bash 复制代码
```
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
```

新建 Kuikly 工程

使用 Android Studio 新建 Kuikly 工程
- 路径：File -> New -> New Project -> Kuikly Project Template

运行鸿蒙 App

注意事项

Kuikly 鸿蒙跨端产物已支持 Windows 平台编译，请参考鸿蒙平台开发方式进行配置
若想通过插件生成 Ohos 工程，需要更新插件至 1.1.0 版本以上

运行步骤

首次运行 Ohos 配置
- 如果是首次运行 Ohos，需要用鸿蒙 DevEco Studio 打开 ohosApp 目录
- 若初次打开鸿蒙 IDE sync 出错，打开 ohosApp 目录下的 .npmrc 文件，右上角点击 sync 重新 sync 即可
配置签名
- 在运行 App 之前，需要执行签名操作
- 路径：File -> Project Structure -> Signing Configs
- 参考文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing#section1240072619462
运行 ohosApp
- 可以选择在 DevEco Studio 内运行或 Android Studio 内运行
- 若 Android Studio 无 ohosApp 选项，重新打开 Android Studio 即可
验证运行结果
- 当手机出现下面界面时，说明已运行成功 ohosApp

开始编写代码

我们来看如何使用 Kuikly 编写经典的 HelloWorld 示例。

步骤 1：创建 Page 类

在 shared/src/commonMain/kotlin/xxx.xxx.xxx/ 目录下新建 pages 目录，并创建 HelloWorldPage 类。

kotlin 复制代码

internal class HelloWorldPage : Pager() {
    override fun body(): ViewBuilder {
        // TODO: 实现页面内容
    }
}

步骤 3：添加页面内容

在 body 方法中，添加一个居中的 Text 组件：

kotlin 复制代码

internal class HelloWorldPage : Pager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

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

步骤 4：添加 @Page 注解

在 HelloWorldPage 类上添加 @Page 注解，指定 Page 的名字，供 Kuikly 在运行时创建该 Page：

kotlin 复制代码

@Page("HelloWorld")
internal class HelloWorldPage : Pager() {
    // ...
}

步骤 5：完整代码

kotlin 复制代码

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

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

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

步骤 6：运行并测试

运行 ohosApp，在 Kuikly 路由页面 输入我们加在 HelloWorldPage 上的注解名字 HelloWorld，最后点击跳转。

常见问题

1. Xcode 相关错误

问题： 在构建 Ohos 项目时遇到 Xcode 相关错误，如 xcodeVersion 任务失败。

原因： Kotlin Multiplatform 插件会检查 Xcode，即使只开发 Ohos 项目。

解决方案：

如果只开发 Android 和 Ohos，可以忽略 Xcode 相关警告
项目已配置自动处理 Xcode 版本文件，构建应该可以正常进行
如果仍有问题，可以安装 Xcode（即使不使用）

2. CocoaPods 配置问题

问题： CocoaPods 要求终端使用 UTF-8 编码。

解决方案： 在 ~/.zprofile 文件中添加：

bash 复制代码

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

然后重新打开终端或运行 source ~/.zprofile

3. Gradle 构建失败

问题： 构建时出现 Kotlin 层次模板警告。

解决方案： 项目已配置使用 Kotlin 的默认层次模板，如果仍有警告，请确保没有显式的 dependsOn() 调用。

4. KSP 版本警告

问题： 出现 ksp-2.0.21-1.0.27 is too old for kotlin-2.0.21-KBA-010 警告。

说明： 这是版本兼容性警告，通常不会影响构建。如需解决，可以升级 KSP 版本或降级 Kotlin 版本。

5. Android Studio 无 ohosApp 选项

解决方案： 重新打开 Android Studio 即可。

参考资源

腾讯端服务官网： https://framework.tds.qq.com/
Kuikly 文档： https://kuikly.tds.qq.com/Introduction/arch.html
项目地址： https://atomgit.com/Tencent-TDS/KuiklyUI
快速开始（HarmonyOS）： https://kuikly.tds.qq.com/QuickStart/harmony.html
鸿蒙平台开发方式： https://kuikly.tds.qq.com/DevGuide/harmony-dev.md
开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net/

Kuikly-OH 实践（mac版本）