Loading...
Loading...
Kuikly 自定义 View 开发助手。指导如何创建自定义 UI 组件,将原生 View 暴露给 Kuikly 侧使用。覆盖完整开发流程:Kuikly 侧组件定义、各平台 Native 侧实现(Android/iOS/鸿蒙ArkTS/H5/小程序)及使用。当用户需要自定义扩展 UI 组件时使用。
npx skill4agent add tencent-tds/kuiklyui-ai kuikly-expand-viewviewNameviewName()setProp(propKey, propValue)call(method, params, callback)viewNameAttrEvent方法DeclarativeBaseView<XxxAttr, XxxEvent>viewName()createAttr()createEvent()AttrAttrEventEventimport com.tencent.kuikly.core.base.DeclarativeBaseView
class MyImageView : DeclarativeBaseView<MyImageAttr, MyImageEvent>() {
override fun createAttr(): MyImageAttr {
return MyImageAttr()
}
override fun createEvent(): MyImageEvent {
return MyImageEvent()
}
// 返回 Native 侧注册的组件名
override fun viewName(): String {
return "HRImageView"
}
// 组件方法(可选),实际实现在 Native 侧
fun test() {
performTaskWhenRenderViewDidLoad {
renderView?.callMethod("test", "params")
}
}
}Attrimport com.tencent.kuikly.core.base.Attr
class MyImageAttr : Attr() {
/**
* 设置图片数据源
* @param src 图片 URL
* @return this(支持链式调用)
*/
fun src(src: String): MyImageAttr {
"src" with src // 将属性透传给原生组件
return this
}
/**
* 设置占位图
*/
fun placeholder(url: String): MyImageAttr {
"placeholder" with url
return this
}
/**
* 设置缩放模式
*/
fun scaleType(type: String): MyImageAttr {
"scaleType" with type
return this
}
}Eventimport com.tencent.kuikly.core.base.event.Event
import com.tencent.kuikly.core.nvi.serialization.json.JSONObject
class MyImageEvent : Event() {
/**
* 图片加载成功回调
*/
fun loadSuccess(handler: (LoadSuccessParams) -> Unit) {
register(LOAD_SUCCESS) {
handler(LoadSuccessParams.decode(it))
}
}
/**
* 图片加载失败回调
*/
fun loadError(handler: (LoadErrorParams) -> Unit) {
register(LOAD_ERROR) {
handler(LoadErrorParams.decode(it))
}
}
companion object {
const val LOAD_SUCCESS = "loadSuccess"
const val LOAD_ERROR = "loadError"
}
}
// 事件参数解析类
data class LoadSuccessParams(
val src: String,
val width: Int,
val height: Int
) {
companion object {
fun decode(params: Any?): LoadSuccessParams {
val tempParams = params as? JSONObject ?: JSONObject()
return LoadSuccessParams(
src = tempParams.optString("src", ""),
width = tempParams.optInt("width", 0),
height = tempParams.optInt("height", 0)
)
}
}
}
data class LoadErrorParams(
val src: String,
val errorCode: Int
) {
companion object {
fun decode(params: Any?): LoadErrorParams {
val tempParams = params as? JSONObject ?: JSONObject()
return LoadErrorParams(
src = tempParams.optString("src", ""),
errorCode = tempParams.optInt("errorCode", 0)
)
}
}
}class MyImageView : DeclarativeBaseView<MyImageAttr, MyImageEvent>() {
// ...
/**
* 重新加载图片(无返回值)
*/
fun reload() {
performTaskWhenRenderViewDidLoad {
renderView?.callMethod("reload", null)
}
}
/**
* 获取图片信息(异步回调)
*/
fun getImageInfo(callback: (width: Int, height: Int) -> Unit) {
performTaskWhenRenderViewDidLoad {
renderView?.callMethod("getImageInfo", null) { result ->
val json = result as? JSONObject
callback(json?.optInt("width") ?: 0, json?.optInt("height") ?: 0)
}
}
}
}⚠️ 注意:
- View 的方法支持异步回调结果,即
,但不支持同步返回结果。renderView?.callMethod("method", "params", callback)- View 方法不支持传递二进制数据,如需传输图片等二进制内容,请通过 Base64 编码后以 JSON 形式传递,或使用 Module 方法实现。
import com.tencent.kuikly.core.base.ViewContainer
fun ViewContainer<*, *>.MyImage(init: MyImageView.() -> Unit) {
addChild(MyImageView(), init)
}override fun body(): ViewBuilder {
val ctx = this
return {
MyImage {
attr {
size(176f, 132f)
src("https://example.com/image.png")
placeholder("https://example.com/placeholder.png")
}
event {
loadSuccess { params ->
println("图片加载成功: ${params.src}, 尺寸: ${params.width}x${params.height}")
}
loadError { params ->
println("图片加载失败: ${params.errorCode}")
}
}
}
}
}ViewRef@Page("MyPage")
class MyPage : Pager() {
// 声明 ViewRef
private val imageRef = ViewRef<MyImageView>()
override fun body(): ViewBuilder {
return {
MyImage {
// 绑定 ref
ref(imageRef)
attr {
src("https://example.com/image.png")
}
}
Button {
attr { title("重新加载") }
event {
click {
// 通过 ref 调用方法
imageRef.view?.reload()
}
}
}
}
}
}setPropcall| 平台 | 基类/协议 | 注册方式 | 注意事项 |
|---|---|---|---|
| Android | | | 继承原生 View 并实现接口 |
| iOS | | 类名必须与 viewName 一致(运行时动态创建) | 属性方法命名 |
| 鸿蒙 (ArkTS) | | | 需实现 |
| H5 | | | 重写 |
| 小程序 | | | 需创建 |
| Kuikly 侧类型 | Native 侧接收类型 |
|---|---|
| |
| 对应基础类型 / |
| |
| |
KuiklyRenderCallback// 保存回调
private var loadSuccessCallback: KuiklyRenderCallback? = null
override fun setProp(propKey: String, propValue: Any): Boolean {
return when (propKey) {
"loadSuccess" -> {
loadSuccessCallback = propValue as KuiklyRenderCallback
true
}
else -> super.setProp(propKey, propValue)
}
}
// 触发回调
private fun onImageLoaded(src: String, width: Int, height: Int) {
loadSuccessCallback?.invoke(mapOf(
"src" to src,
"width" to width,
"height" to height
))
}| ❌ 错误做法 | ✅ 正确做法 |
|---|---|
| View 名字 Kuikly 侧与 Native 侧不一致 | 确保 |
| 自定义 View 未设置宽高导致不显示 | 自定义 View 跨端侧使用时必须显式设置宽高(如 |
| iOS 侧 View 类名与 Kuikly 侧 viewName 不一致 | iOS 通过类名动态创建 View,类名必须与 |
iOS 侧用 Swift 实现但未加 | Swift 实现的 View 需要 |
鸿蒙侧忘记实现 | 鸿蒙侧必须实现此方法返回 |
| 忘记在 Native 侧注册自定义 View | 自定义 View 必须注册后才能使用 |
在 | View 方法必须在 |