Kuikly 自定义 Module 开发

Contents

• [Core Guidelines](#core-guidelines)
• [Workflow: Creating Custom Module (Kuikly Side)](#workflow-creating-module-kuikly-side)
• [Workflow: Implementing Native Side Module](#workflow-implementing-native-side-module)

Core Guidelines

• Module 是平台 API 的统一接口： Kuikly 本身不具备平台相关能力，通过 Module 机制将 Native API 暴露给 Kuikly 侧调用。
• 自定义 Module 需双端实现： Kuikly 侧定义 API 接口，Native 侧（Android/iOS/鸿蒙/H5/小程序）实现具体逻辑，通过 moduleName 关联。
• 通信方式分同步和异步： 同步调用（syncToNativeMethod）在 Kuikly 线程执行，异步调用（asyncToNativeMethod）在主线程执行。同步调用避免耗时操作。
• Module 名字必须全端一致： Kuikly 侧 moduleName() 返回值必须与 Native 侧注册的名字完全一致。

Workflow: Creating Module (Kuikly Side)

Use this workflow to create a custom Module on the Kuikly (Kotlin) side.

步骤：

1. 新建 Module 类继承 Module，实现 moduleName() 方法。
2. 编写业务 API 方法，通过 toNative / syncToNativeMethod / asyncToNativeMethod 与 Native 通信。
3. 在 Pager 的 createExternalModules() 中注册 Module。
4. 在业务代码中通过 acquireModule 获取并使用。

Step 1: 定义 Module 类

import com.tencent.kuikly.core.module.Module
import com.tencent.kuikly.core.module.CallbackFn
import com.tencent.kuikly.core.nvi.serialization.json.JSONObject

class MyLogModule : Module() {

    override fun moduleName(): String = "KRMyLogModule"

    companion object {
        const val MODULE_NAME = "KRMyLogModule"
    }
}

Step 2: 编写 API 方法

Module 提供以下通信方法：

异步调用（无返回值）：

fun log(content: String) {
    asyncToNativeMethod(
        "log",
        JSONObject().apply { put("content", content) },
        null
    )
}

异步调用（带回调）：

fun logWithCallback(content: String, callbackFn: CallbackFn) {
    asyncToNativeMethod(
        "logWithCallback",
        JSONObject().apply { put("content", content) },
        callbackFn
    )
}

同步调用（有返回值）：

fun syncLog(content: String): String {
    return syncToNativeMethod(
        "syncLog",
        JSONObject().apply { put("content", content) },
        null
    )
}

二进制数据传输（使用 Array<Any> 参数）：

fun uploadData(bytes: ByteArray): Any? {
    return syncToNativeMethod(
        "uploadData",
        arrayOf<Any>(bytes),
        null
    )
}

常驻回调（keepCallbackAlive = true）：

fun registerListener(callbackFn: CallbackFn): CallbackRef {
    val result = toNative(
        true,           // keepCallbackAlive: callback 不会被自动销毁
        "registerListener",
        null,
        callbackFn,
        false
    )
    return result.callbackRef!!
}

// 手动移除回调
fun unregisterListener(callbackRef: CallbackRef) {
    removeCallback(callbackRef)
}

Step 3: 注册 Module

自定义 Module 需要在 Pager 或 ComposeContainer 的 createExternalModules() 中注册，两种 DSL 的注册方式一致。

Kuikly DSL 注册：

import com.tencent.kuikly.core.annotations.Page
import com.tencent.kuikly.core.module.Module

@Page("MyPage")
internal class MyPage : Pager() {

    override fun createExternalModules(): Map<String, Module>? {
        return mapOf(
            MyLogModule.MODULE_NAME to MyLogModule()
        )
    }

    // 如果有基类 BasePager 已注册了其他 Module，需要合并：
    // override fun createExternalModules(): Map<String, Module>? {
    //     val modules = (super.createExternalModules() as? HashMap) ?: hashMapOf()
    //     modules[MyLogModule.MODULE_NAME] = MyLogModule()
    //     return modules
    // }

    override fun body(): ViewBuilder { ... }
}

Compose DSL 注册：

import com.tencent.kuikly.compose.ComposeContainer
import com.tencent.kuikly.compose.setContent
import com.tencent.kuikly.core.annotations.Page
import com.tencent.kuikly.core.module.Module

@Page("MyComposePage")
class MyComposePage : ComposeContainer() {

    // 注册方式与 Kuikly DSL 完全一致
    override fun createExternalModules(): Map<String, Module>? {
        return mapOf(
            MyLogModule.MODULE_NAME to MyLogModule()
        )
    }

    override fun willInit() {
        super.willInit()
        setContent {
            MyScreen()
        }
    }
}

Step 4: 使用 Module

Kuikly DSL 中使用：

override fun created() {
    super.created()

    val myLogModule = acquireModule<MyLogModule>(MyLogModule.MODULE_NAME)

    // 异步调用
    myLogModule.log("test log")

    // 异步调用带回调
    myLogModule.logWithCallback("log with callback") { data ->
        val result = data  // Native 侧返回的 JSONObject
    }

    // 同步调用
    val result = myLogModule.syncLog("sync log")
}

Compose DSL 中使用：

import androidx.compose.runtime.Composable
import com.tencent.kuikly.compose.ui.platform.LocalActivity
import com.tencent.kuikly.core.pager.Pager

@Composable
fun MyScreen() {
    val pager = LocalActivity.current.getPager() as Pager
    val myLogModule = pager.acquireModule<MyLogModule>(MyLogModule.MODULE_NAME)

    // 异步调用
    myLogModule.log("test log")

    // 异步调用带回调
    myLogModule.logWithCallback("log with callback") { data ->
        val result = data  // Native 侧返回的 JSONObject
    }

    // 同步调用
    val result = myLogModule.syncLog("sync log")
}

Workflow: Implementing Native Side Module

Use this workflow to implement the Native side of a custom Module.

前提： 只需在业务需要支持的平台上实现 Native 侧 Module，无需实现所有平台。

步骤：

1. 确定需要支持的目标平台（Android/iOS/鸿蒙/H5/小程序）。
2. 在目标平台宿主工程中创建对应的 Module 类。
3. 实现 call 方法，根据 method 分发处理。
4. 将 Module 注册到 Kuikly 框架。

💡 鸿蒙平台备注： 鸿蒙提供 ArkTS 和 C 两种实现方式，一般情况只需选择 ArkTS 实现即可。

各平台实现详见 [MODULEIMPLEMENT.md](references/MODULEIMPLEMENT.md)

速查：各平台 Module 基类与注册方式

Native 侧支持的数据类型

数据序列化规则

⚠️ syncToNativeMethod 和 asyncToNativeMethod 传入 JSONObject 参数时会序列化为 JSON 字符串，不支持 ByteArray 二进制数据。传输二进制请使用 Array<Any> 参数的重载方法。

常见陷阱与正确做法