欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

引言

在移动应用开发领域，跨平台技术始终是开发者关注的焦点。如何用一套代码高效适配多端，同时兼顾原生性能与开发体验，是许多团队面临的核心诉求。腾讯 Oteam 推出的 KuiklyUI 框架，基于 Kotlin Multiplatform（KMP）实现了 "一套代码多端运行" 的核心目标，完美平衡了原生性能、易用性与动态化能力，已在腾讯内部多款核心产品中落地验证。

本文将以 Windows 平台为基础，详细记录从 KuiklyUI-mini 模板项目（https://gitcode.com/Goway_Hui/KuiklyUI-mini?isLogin=1）出发，逐步构建并完善跨平台汇率换算应用（成品项目：https://gitcode.com/Goway_Hui/Kuikly-exchange-rate?isLogin=1）的全过程。从环境搭建、项目初始化到功能实现、多端部署，每个环节都将提供详细的操作步骤与核心代码解析，旨在帮助开发者快速掌握 KuiklyUI 的实战技巧，轻松上手跨平台应用开发。无论你是鸿蒙开发初学者，还是寻求跨平台解决方案的资深开发者，都能从本文中获得实用的开发经验与技术参考。

1. 技术选型与核心优势解析

1.1 为什么选择 KuiklyUI？

在众多跨平台框架中，KuiklyUI 凭借其独特的技术架构与产品特性脱颖而出，尤其适合企业级应用开发：

1.跨端高效复用：一套 Kotlin 代码可直接适配 Android、iOS、鸿蒙等多平台，无需为不同端单独开发，极大降低了开发成本与维护成本，代码复用率高达 90% 以上。

2.原生性能体验：采用原生渲染方式，无桥接损耗，SDK 体积轻量，应用启动速度与运行流畅度媲美原生应用，避免了部分跨平台框架常见的卡顿问题。

3.低学习成本门槛：沿用 Kotlin 生态与原生开发工具链，开发者无需学习全新的技术栈，只需具备基础的 Kotlin 编程能力，即可快速上手开发。

4.开发模式灵活：同时支持声明式编程与响应式编程，可根据团队开发习惯与项目需求灵活选择，适配不同场景下的开发需求。

5.动态迭代能力：支持 UI 界面与业务逻辑的动态更新，无需重新发版即可实现功能升级与问题修复，提升产品迭代效率。

6.企业级稳定性：经过腾讯内部多款核心产品的大规模用户验证，在高并发、复杂场景下仍能保持稳定运行，具备成熟的兼容性与可靠性。

2. 环境准备与项目初始化

2.1 核心开发环境清单

1.JDK17+（推荐 AdoptOpenJDK 17）

2.Android Studio最新版本（内置 KMP 插件）

3.Kotlin Multiplatform Plugin1.9.0+

4.Android SDKAPI 33+

5.Android SDK Build-Tools33.0.2+

6.DevEco Studio5.0+

7.鸿蒙 SDKAPI Version 9+Git最新稳定版

8.Node.js（可选）

9.LTS 版本（18.x+）

2.2 项目初始化：基于 KuiklyUI-mini 模板构建

2.2.1 下载 KuiklyUI-mini 模板

1.打开浏览器，访问 GitCode 仓库地址：https://gitcode.com/Goway_Hui/KuiklyUI-mini?isLogin=1

2.下载.zip文件

3.解压至你平常做项目用的文件夹里面

2.2.2 项目结构解析

解压后的项目结构如下，基于 KMP 的多模块架构设计，确保多端代码的分离与复用：

KuiklyExchangeRate/
├── buildSrc/                // 构建脚本配置（依赖版本、构建规则等）
├── compose/                 // Compose相关组件（可选）
├── core/                    // 核心模块（多端共享代码）
│   ├── commonMain/          // 通用代码（业务逻辑、数据模型等）
│   ├── androidMain/         // Android端专属代码
│   ├── iosMain/             // iOS端专属代码
│   └── ohosMain/            // 鸿蒙端专属代码
├── androidApp/              // Android应用模块（入口工程）
├── iosApp/                  // iOS应用模块（入口工程）
├── ohosApp/                 // 鸿蒙应用模块（入口工程）
├── demo/                    // 演示模块（可选，用于功能测试）
├── gradle/                  // Gradle配置文件
├── gradlew                  // Gradle命令行工具（Windows）
├── gradlew.bat              // Gradle命令行工具（Linux/Mac）
└── settings.gradle.kts      // 项目模块配置

核心模块说明：

1.commonMain：多端共享的核心代码，包括数据模型、业务逻辑、通用工具类等，是跨平台开发的核心所在

2.各端 Main（androidMain/iosMain/ohosMain）：对应平台的专属代码，如原生组件适配、平台特有功能实现等

3.各端 App 模块：对应平台的应用入口，包含启动配置、权限申请、页面路由等

2.2.3 项目基础配置修改

为适配汇率换算应用的需求，需对模板项目的基础配置进行修改：

1.修改项目名称与包名

打开 settings.gradle.kts 文件，修改 rootProject.name 为 "KuiklyExchangeRate"

rootProject.name = "KuiklyExchangeRate"
include(":core")
include(":androidApp")
include(":ohosApp")
include(":demo")
// 如需支持iOS，添加include(":iosApp")

打开 core 模块的 build.gradle.kts 文件，修改包名配置：

kotlin {
    androidTarget()
    // iosX64()
    // iosArm64()
    // iosSimulatorArm64()
    ohosTarget()
    
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(platform("com.tencent.kuikly:kuikly-bom:1.0.0"))
                implementation("com.tencent.kuikly:kuikly-core")
                implementation("com.tencent.kuikly:kuikly-network")
                implementation("com.tencent.kuikly:kuikly-storage")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("com.tencent.kuikly:kuikly-render-android")
            }
        }
        val ohosMain by getting {
            dependencies {
                implementation("com.tencent.kuikly:kuikly-render-ohos")
            }
        }
        // 其他平台配置...
    }
}

批量修改代码中的包名：将原模板中的包名（如 com.tencent.kuikly.mini）替换为 com.goway.kuikly.exchangerate（可使用 Android Studio 的 Replace in Path 功能，快捷键 Ctrl+Shift+R）

2.配置依赖版本

打开 buildSrc/src/main/kotlin/Dependencies.kt 文件，统一管理依赖版本：

object Versions {
    const val kotlin = "1.9.20"
    const val kuikly = "1.0.0"
    const val coroutines = "1.7.3"
    const val retrofit = "2.9.0"
    const val gson = "2.10.1"
}

object Dependencies {
    // KuiklyUI核心依赖
    const val kuiklyBom = "com.tencent.kuikly:kuikly-bom:${Versions.kuikly}"
    const val kuiklyCore = "com.tencent.kuikly:kuikly-core"
    const val kuiklyNetwork = "com.tencent.kuikly:kuikly-network"
    const val kuiklyStorage = "com.tencent.kuikly:kuikly-storage"
    const val kuiklyRenderAndroid = "com.tencent.kuikly:kuikly-render-android"
    const val kuiklyRenderOhos = "com.tencent.kuikly:kuikly-render-ohos"
    
    // 其他依赖
    const val kotlinCoroutines = "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}"
    const val gson = "com.google.code.gson:gson:${Versions.gson}"
    const val retrofit = "com.squareup.retrofit2:retrofit:${Versions.retrofit}"
    const val retrofitGsonConverter = "com.squareup.retrofit2:converter-gson:${Versions.retrofit}"
}

3.同步项目依赖

1.打开 Android Studio，点击 File > Open，选择 KuiklyExchangeRate 项目文件夹

2.等待项目加载完成后，点击 Gradle 工具栏中的 "Sync Project with Gradle Files" 按钮（图标为大象）

3.同步过程中，Android Studio 会自动下载所需依赖，若出现依赖下载失败，可检查网络连接或 Gradle 镜像配置

2.2.4 测试模板项目运行

为确保项目初始化成功，需先测试模板项目在 Android 与鸿蒙平台的运行情况：

Android 平台测试

1.打开 Android Studio和外部模拟器，Android Studio能自动识别并连接外部模拟器

2.点击运行按钮（绿色三角形图标），或使用快捷键 Shift+F10

3.运行成功效果如图所示

鸿蒙云真机测试

1.打开 DevEco Studio，导入ohosApp 模块，配置证书和签名文件，编译.so和.abc文件

找到.bat文件，点击运行，运行成功后，就会有.so文件

2.构建HAP包

3.打开云真机，点击我们刚刚弄好的项目，上传.hap文件，运行成功效果如图所示

3. 数据模型构建

3.1 数据模型设计

数据模型采用 Kotlin 数据类实现，聚焦核心字段，剔除冗余属性，确保多端共享时数据结构简洁、解析高效，所有模型均放置在core模块的commonMain目录下，支持 Android、鸿蒙多端复用。

3.1.1 核心数据模型

1. 货币实体（Currency.kt）

存储单种货币的基础标识信息，支撑货币选择、展示功能:

package com.goway.kuikly.exchangerate.data.model

/**
 * 货币实体（核心字段：代码、名称、符号、图标路径）
 * @param code 国际标准三位货币代码（如CNY、USD）
 * @param name 货币中文名称（如人民币、美元）
 * @param symbol 货币符号（如¥、$）
 * @param iconRes 货币图标相对路径（多端统一资源格式）
 */
data class Currency(
    val code: String,
    val name: String,
    val symbol: String,
    val iconRes: String
)

2. 汇率实体（ExchangeRate.kt)

存储单条实时汇率数据，支撑换算、缓存功能：

package com.goway.kuikly.exchangerate.data.model

import java.util.Date

/**
 * 汇率实体（核心字段：基准货币、目标货币、汇率值、更新时间）
 * @param baseCurrency 基准货币代码
 * @param targetCurrency 目标货币代码
 * @param rate 汇率值（1单位基准货币可兑换的目标货币数量）
 * @param updateTime 汇率更新时间（用于判断缓存是否过期）
 */
data class ExchangeRate(
    val baseCurrency: String,
    val targetCurrency: String,
    val rate: Double,
    val updateTime: Date = Date()
)

3. 收藏货币对（FavoriteCurrencyPair.kt）

存储用户收藏的货币对信息，支撑收藏列表功能:

package com.goway.kuikly.exchangerate.data.model

import java.util.Date

/**
 * 收藏货币对实体（核心字段：唯一ID、货币对、收藏时间）
 * @param id 唯一标识（采用时间戳生成，避免重复）
 * @param baseCurrency 基准货币代码
 * @param targetCurrency 目标货币代码
 * @param createTime 收藏时间（用于列表排序）
 */
data class FavoriteCurrencyPair(
    val id: Long,
    val baseCurrency: String,
    val targetCurrency: String,
    val createTime: Date = Date()
)

4. 汇率预警（RateAlert.kt）

存储用户设置的预警信息，支撑预警提醒功能：

package com.goway.kuikly.exchangerate.data.model

/**
 * 汇率预警实体（核心字段：唯一ID、货币对、阈值、预警类型）
 * @param id 唯一标识（采用时间戳生成）
 * @param baseCurrency 基准货币代码
 * @param targetCurrency 目标货币代码
 * @param threshold 预警阈值
 * @param alertType 预警类型（高于/低于阈值）
 * @param isEnabled 是否启用预警（默认启用）
 */
data class RateAlert(
    val id: Long,
    val baseCurrency: String,
    val targetCurrency: String,
    val threshold: Double,
    val alertType: AlertType,
    val isEnabled: Boolean = true
)

/**
 * 预警类型枚举（简化为两种核心类型）
 */
enum class AlertType {
    ABOVE_THRESHOLD, // 高于阈值
    BELOW_THRESHOLD  // 低于阈值
}

5. 转换结果（ConversionResult.kt）

存储单次货币转换记录，支撑转换历史回溯功能：

package com.goway.kuikly.exchangerate.data.model

import java.util.Date

/**
 * 转换结果实体（核心字段：金额、货币对、汇率、转换时间）
 * @param sourceAmount 源货币金额
 * @param sourceCurrency 源货币代码
 * @param targetAmount 目标货币金额
 * @param targetCurrency 目标货币代码
 * @param rate 本次转换使用的汇率值
 * @param conversionTime 转换时间（用于历史记录排序）
 */
data class ConversionResult(
    val sourceAmount: Double,
    val sourceCurrency: String,
    val targetAmount: Double,
    val targetCurrency: String,
    val rate: Double,
    val conversionTime: Date = Date()
)

3.2数据源设计

采用Repository设计模式，统一封装网络与本地数据源，对外提供简洁接口，屏蔽底层数据获取细节，确保上层业务逻辑无需关注数据来源。

3.2.1 核心数据源接口

package com.goway.kuikly.exchangerate.data.datasource

import com.goway.kuikly.exchangerate.data.model.ExchangeRate
import com.goway.kuikly.exchangerate.data.model.FavoriteCurrencyPair
import com.goway.kuikly.exchangerate.data.model.RateAlert
import kotlinx.coroutines.flow.Flow
import java.util.Date

/**
 * 汇率数据源统一接口（简化核心方法，剔除冗余操作）
 */
interface ExchangeRateDataSource {
    // 获取实时汇率（网络数据源实现）
    suspend fun getLatestRates(baseCurrency: String): List<ExchangeRate>
    
    // 保存汇率到本地缓存
    suspend fun saveCachedRates(rates: List<ExchangeRate>)
    
    // 获取本地缓存汇率
    suspend fun getCachedRates(baseCurrency: String): List<ExchangeRate>?
    
    // 保存收藏货币对
    suspend fun saveFavoritePair(pair: FavoriteCurrencyPair)
    
    // 获取收藏列表（返回Flow支持响应式更新）
    fun getFavoritePairs(): Flow<List<FavoriteCurrencyPair>>
    
    // 保存汇率预警
    suspend fun saveRateAlert(alert: RateAlert)
    
    // 检查是否触发预警
    suspend fun checkTriggeredAlerts(baseCurrency: String): List<RateAlert>
}

总结

本文聚焦 Windows 平台下 KuiklyUI 框架的实战应用，以 “从模板到成品” 的思路，完成了跨平台汇率换算应用的核心开发。核心设计围绕 “简洁实用” 展开，功能上剔除冗余场景，保留实时汇率查询、货币转换计算、常用货币收藏等 6 大核心功能，覆盖用户日常汇率使用的核心需求；数据模型采用轻量设计，仅保留支撑业务的关键字段，确保多端共享时的解析效率与一致性。

技术实现上，充分发挥 KuiklyUI 的跨平台优势，基于 Kotlin Multiplatform 实现一套代码适配 Android 与鸿蒙，借助框架内置的响应式状态管理与声明式 UI，简化了状态同步与界面构建逻辑。同时通过 Repository 模式封装数据源，实现网络数据与本地缓存的协同，既保证了离线使用能力，又提升了应用响应速度。

整个开发过程避开复杂冗余的实现，聚焦核心流程与必要代码，降低了跨平台开发的学习与落地成本。最终成品不仅具备完整的汇率换算能力，还保持了原生级的性能体验与简洁的用户交互，为开发者提供了一套 “轻量化、可复用、易扩展” 的 KuiklyUI 实战方案，可直接作为同类跨平台应用开发的参考模板。