同时开发 Android、iOS、鸿蒙 App 的最佳实践：Kuikly 一套代码搞定

┌──────────────────────────────────────────────────────┐
│         业务代码层（Kotlin，commonMain）               │
│         Compose DSL / Kuikly DSL                     │
├──────────────────────────────────────────────────────┤
│         KMP 跨平台共享层                              │
│         expect/actual 机制 · Bridge 通信              │
├──────────────────────────────────────────────────────┤
│         平台原生渲染层                                │
│  Android → .aar（FrameLayout）                       │
│  iOS     → .framework（UIView）                      │
│  HarmonyOS → .so（ArkUI）                            │
└──────────────────────────────────────────────────────┘

src/
├── commonMain/        # 跨平台共享代码（90%+ 代码在此）
│   └── kotlin/
│       └── com/example/
│           ├── pages/     # 页面
│           ├── components/ # 组件
│           └── data/      # 数据模型
├── androidMain/       # Android 平台特有实现
├── iosMain/           # iOS 平台特有实现
└── ohosArm64Main/     # HarmonyOS 平台特有实现

Android Studio → Settings → Plugins → Marketplace → 搜索 "Kuikly" → Install

File → New → New Project → Kuikly Project Template
→ 选择 DSL 类型（Compose）
→ 勾选平台：Android ✅ iOS ✅ HarmonyOS ✅
→ 完成创建

plugins {
    kotlin("multiplatform")
    id("com.google.devtools.ksp") version "1.9.22-1.0.17"
}

kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.tencent.kuikly-open:core:$kuiklyVersion")
                implementation("com.tencent.kuikly-open:compose:$kuiklyVersion")
            }
        }
    }
}

dependencies {
    add("kspCommonMainMetadata", "com.tencent.kuikly-open:core-ksp:$kuiklyVersion")
}

// Kuikly 2.5.0+ 需要添加 maven 源
repositories {
    maven("https://mirrors.tencent.com/nexus/repository/maven-tencent/")
}

dependencies {
    implementation("com.tencent.kuikly-open:core-render-android:$kuiklyVersion")
}

source 'https://cdn.cocoapods.org/'
platform :ios, '14.1'

target 'iosApp' do
  inhibit_all_warnings!
  pod 'OpenKuiklyIOSRender', '$kuiklyVersion'
end

https://github.com/Tencent-TDS/KuiklyUI.git

{
  "dependencies": {
    "kuikly-ohos-compile-plugin": "latest"
  }
}

// commonMain：只需一个注解，KSP 编译时自动生成路由注册代码
@Page(name = "homePage")
class HomePage : ComposeContainer() {

    @Composable
    override fun Content() {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .background(Color.White),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Text(
                text = "Hello, 三端统一！",
                fontSize = 24.sp,
                color = Color.Black
            )
            Spacer(modifier = Modifier.height(16.dp))
            Button(onClick = { /* 跳转逻辑 */ }) {
                Text("进入详情页")
            }
        }
    }
}

// 编译时自动生成，开发者无需关心
class KuiklyCoreEntry {
    fun triggerRegisterPages() {
        router.registerPage("homePage", HomePage::class)
    }
}

// commonMain：声明跨平台抽象
expect fun getPlatformName(): String

// androidMain：Android 实现
actual fun getPlatformName(): String = "Android"

// iosMain：iOS 实现
actual fun getPlatformName(): String = "iOS"

// ohosArm64Main：鸿蒙实现
actual fun getPlatformName(): String = "HarmonyOS"

@Page(name = "feedPage")
class FeedPage : ComposeContainer() {

    private val items = (1..100).map { "Item $it" }

    @Composable
    override fun Content() {
        // LazyColumn 三端均支持按需渲染，优化长列表性能
        LazyColumn(modifier = Modifier.fillMaxSize()) {
            items(
                count = items.size,
                key = { index -> index }
            ) { index ->
                FeedItem(text = items[index])
            }
        }
    }
}

@Composable
private fun FeedItem(text: String) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .height(60.dp)
            .padding(horizontal = 16.dp, vertical = 8.dp)
    ) {
        Text(text = text, fontSize = 16.sp)
    }
}

// commonMain：通过 Bridge 调用各平台原生能力
class NetworkModule : Module() {

    fun fetchData(url: String, callback: (String) -> Unit) {
        // Bridge 自动将调用转发到各平台原生网络实现
        nativeBridge.call(
            method = "network.get",
            params = mapOf("url" to url)
        ) { result ->
            callback(result.toString())
        }
    }
}

// buildSrc/src/main/java/KuiklyVersions.kt
object KuiklyVersions {
    const val KUIKLY = "2.x.x"  // 三端版本号必须保持一致！
}

Page not registered     → 检查 @Page 注解是否正确，KSP 是否执行
KSP not executed        → 确认 KSP 插件已启用，执行 Build → Clean Project
ClassNotFoundException  → 检查依赖配置，三端版本号是否一致
iOS 线程崩溃            → 所有 Kuikly UI 操作必须在主线程调用