Kuikly 原生 API 扩展机制对比总结,小程序跳过
1. Kuikly 侧(通用)
-
核心类 :继承
Module
基类,实现moduleName()
方法。 -
通信方式:
- 异步调用 :通过
toNative
方法传递callbackFn
接收返回值。 - 同步调用 :通过
toNative
设置syncCall=true
直接返回结果。
- 异步调用 :通过
-
注册方式 :在
Pager
子类中重写createExternalModules
,以键值对形式注册模块(键名需与原生侧一致)。 -
辅助方法 :提供
syncToNativeMethod
和asyncToNativeMethod
简化调用。
2. Android 侧
-
核心类 :继承
KuiklyRenderBaseModule
,重写call
方法(区分参数类型)。 -
方法实现:
- 通过
method
参数匹配 Kuikly 侧方法名。 - 无返回值方法:直接执行原生逻辑(如
Log.d
)。 - 异步回调:通过
KuiklyRenderCallback.invoke
返回结果。 - 同步返回:直接
return
结果(如字符串)。
- 通过
-
注册方式 :在
registerExternalModule
中调用moduleExport
,键名需与 Kuikly 侧一致。
3. iOS 侧
-
核心类 :继承
KRBaseModule
,类名必须与 Kuikly 侧注册名一致(如KRMyLogModule
)。 -
方法实现:
- 方法名与 Kuikly 侧
toNative
的methodName
严格匹配。 - 参数固定为
NSDictionary
,通过HR_PARAM_KEY
提取参数。 - 异步回调:从参数中获取
KuiklyRenderCallback
并调用。 - 同步返回:直接
return
结果。
- 方法名与 Kuikly 侧
-
特点:依赖运行时动态查找方法,需严格命名。
4. 鸿蒙侧(ArkTS)
-
核心类 :继承
KuiklyRenderBaseModule
,需实现syncMode()
(决定是否支持同步调用)。 -
方法实现:
- 通过
switch-case
分发method
调用。 - 异步回调:调用
callback
函数返回结果。 - 同步返回:直接
return
结果。
- 通过
-
注册方式 :在
getCustomRenderModuleCreatorRegisterMap
中通过Map
注册模块。
关键对比点
端 | 基类 | 方法匹配方式 | 回调机制 | 同步支持 | 注册方式 |
---|---|---|---|---|---|
Kuikly | Module |
方法名直接调用 | CallbackFn 或同步返回 |
是(syncCall ) |
createExternalModules 映射注册 |
Android | KuiklyRenderBaseModule |
call 方法内 switch |
KuiklyRenderCallback.invoke |
是 | moduleExport 动态注册 |
iOS | KRBaseModule |
方法名动态反射 | 从参数提取 callback 调用 |
是 | 类名必须与 Kuikly 侧一致(自动注册) |
鸿蒙 | KuiklyRenderBaseModule |
call 方法内 switch |
直接调用 callback 参数 |
需 syncMode() 返回 true |
Map 键值对注册 |
注意事项
-
命名一致性:Kuikly 与原生侧的模块名、方法名必须严格一致(iOS 侧类名需完全匹配)。
-
线程模型:
- Android/iOS 异步回调默认在主线程,同步调用在子线程。
- 鸿蒙需通过
syncMode()
显式声明是否支持同步。
-
参数传递:
- 基本类型/数组可直接传递,JSON 需序列化为字符串。
- iOS 参数统一封装为
NSDictionary
,鸿蒙/Android 可灵活处理。
通过这套机制,Kuikly 实现了跨平台 API 的统一扩展,开发者只需遵循各端规范即可复用原生能力。