tencent-tds/kuiklyui-ai

kuikly-expand-view

Kuikly 自定义 View 开发助手。指导如何创建自定义 UI 组件,将原生 View 暴露给 Kuikly 侧使用。覆盖完整开发流程:Kuikly 侧组件定义、各平台 Native 侧实现(Android/iOS/鸿蒙ArkTS/H5/小程序)及使用。当用户需要自定义扩展 UI 组件时使用。

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/tencent-tds/kuiklyui-ai --skill kuikly-expand-view

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Contents

Core Guidelines

  • View 是跨平台 UI 组件的统一接口: Kuikly 已封装常用 View(Text、Image、List 等),自定义 View 用于复用已有原生 UI 组件或满足特殊需求。
  • 自定义 View 需双端实现: Kuikly 侧定义组件结构(viewName、Attr、Event),Native 侧(Android/iOS/鸿蒙/H5/小程序)实现具体渲染逻辑,通过 viewName 关联。
  • 组件名必须全端一致: Kuikly 侧 viewName() 返回值必须与 Native 侧注册的名字完全一致。
  • 属性和事件走 setProp 方法: Native 侧通过 setProp(propKey, propValue) 接收 Kuikly 侧设置的属性和事件。
  • 方法调用走 call 方法: Native 侧通过 call(method, params, callback) 响应 Kuikly 侧的方法调用。

Workflow: Creating Expand View (Kuikly Side)

Use this workflow to create a expand View on the Kuikly (Kotlin) side.

Kuikly 组件由四部分组成:

  1. viewName: 组件对应到原生组件的名字
  2. Attr: 组件的属性,用于指定该组件含有哪些属性
  3. Event: 用于接收来自原生组件发送的事件
  4. 方法: 组件本身支持的方法,最终实现在原生侧

步骤:

  1. 新建 View 类继承 DeclarativeBaseView<XxxAttr, XxxEvent>
  2. 实现 viewName()、createAttr()、createEvent() 方法
  3. 定义 Attr 类继承 Attr,添加属性方法
  4. 定义 Event 类继承 Event,添加事件注册方法
  5. 编写声明式 API 扩展函数
  6. 在业务代码中使用组件

Step 1: 定义 View 类

kotlin
import 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")
        }
    }
}

Step 2: 定义 Attr 类

Attr 表示组件支持的属性集。

kotlin
import 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
    }
}

Step 3: 定义 Event 类

Event 表示组件支持的事件。

kotlin
import 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)
            )
        }
    }
}

Step 4: 组件方法(可选)

组件方法是 Kuikly 侧暴露的 API,实际实现在 Native 侧。

kotlin
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 方法实现。

Step 5: 编写声明式 API

kotlin
import com.tencent.kuikly.core.base.ViewContainer

fun ViewContainer<*, *>.MyImage(init: MyImageView.() -> Unit) {
    addChild(MyImageView(), init)
}

Step 6: 业务使用

kotlin
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 获取组件引用

通过 ViewRef 可以获取组件实例,在 Pager 其他位置调用组件方法。

kotlin
@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()
                    }
                }
            }
        }
    }
}

Workflow: Implementing Native Side View

Use this workflow to implement the Native side of a expand View.

前提: 只需在业务需要支持的平台上实现 Native 侧 View,无需实现所有平台。

步骤:

  1. 确定需要支持的目标平台(Android/iOS/鸿蒙/H5/小程序)。
  2. 在目标平台宿主工程中创建对应的 View 类。
  3. 实现 setProp 方法处理属性和事件。
  4. 实现 call 方法处理方法调用。
  5. 将 View 注册到 Kuikly 框架。

各平台实现详见 VIEW_IMPLEMENT.md

速查:各平台 View 基类与注册方式

平台基类/协议注册方式注意事项
AndroidIKuiklyRenderViewExportregisterExternalRenderView 中 renderViewExport(name) { View(ctx) }继承原生 View 并实现接口
iOSKuiklyRenderViewExportProtocol类名必须与 viewName 一致(运行时动态创建)属性方法命名 setCss_xxx,方法命名 css_xxx
鸿蒙 (ArkTS)KuiklyRenderBaseViewgetCustomRenderViewCreatorRegisterMap 或 getCustomRenderViewCreatorRegisterMapV2 中注册需实现 createArkUIView() 返回 ComponentContent
H5IKuiklyRenderViewExportregisterExternalRenderView 中 renderViewExport(name) { View() }重写 ele 属性返回 DOM 元素
小程序IKuiklyRenderViewExportregisterExternalRenderView + Transform.addComponentsAlias + base.wxml 模板需创建 MiniXxxElement 并配置模板

Native 侧 setProp 支持的数据类型

Kuikly 侧类型Native 侧接收类型
StringString / NSString
Int / Float / Double对应基础类型 / NSNumber
BooleanBoolean / BOOL
Event 回调KuiklyRenderCallback

事件触发机制

在 Native 侧,事件通过 KuiklyRenderCallback 回调给 Kuikly 侧:

kotlin
// 保存回调
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 侧不一致确保 viewName() 返回值与 Native 注册名完全一致
自定义 View 未设置宽高导致不显示自定义 View 跨端侧使用时必须显式设置宽高(如 size(w, h)),否则可能不会显示
iOS 侧 View 类名与 Kuikly 侧 viewName 不一致iOS 通过类名动态创建 View,类名必须与 `viewName()` 一致
iOS 侧用 Swift 实现但未加 @objc 注解Swift 实现的 View 需要 @objc 或 @objcMembers 修饰
鸿蒙侧忘记实现 createArkUIView()鸿蒙侧必须实现此方法返回 ComponentContent
忘记在 Native 侧注册自定义 View自定义 View 必须注册后才能使用
在 performTaskWhenRenderViewDidLoad 之外调用 renderViewView 方法必须在 performTaskWhenRenderViewDidLoad 回调中调用

같은 저장소의 Skills

더 많은 Skills

모든 Skills
tencent-tds
커뮤니티

kuikly-animation

Kuikly DSL 动画开发助手(Kuikly DSL)。指导使用声明式和命令式两种方式实现 transform、opacity、backgroundColor、frame 等属性动画,涵盖串行/并行编排与动画取消。当用户需要实现动画效果时使用。

1시간 설치 수
1
GitHub Stars
137
업데이트
8월 10일
tencent-tds
커뮤니티

kuikly-compose-interop-dsl

Compose DSL 混用 Kuikly DSL 完整开发助手。指导如何在 Compose DSL 页面中嵌入 Kuikly DSL 组件(DeclarativeBaseView / ViewContainer)及在 Compose 中调用 Kuikly Module。当用户需要在 Compose 页面中复用 Kuikly DSL 组件、封装原生 View 为 Composable、在 Compose 中调用 Kuikly Module时使用。

1시간 설치 수
1
GitHub Stars
137
업데이트
8월 10일
tencent-tds
커뮤니티

kuikly-coroutines-threading

Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程,包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。

1시간 설치 수
1
GitHub Stars
137
업데이트
8월 10일
tencent-tds
커뮤니티

kuikly-expand-api

Kuikly 自定义 Module 开发助手。指导如何创建自定义 Module,扩展原声API。覆盖完整开发流程:Kuikly 侧 Module 定义、Pager/ComposeContainer 注册、各平台 Native 侧实现、Module 注册,及使用。当用户需要自定义 Module、扩展原生 API、实现 Kuikly 与 Native 双向通信、在各平台实现 Module 的 Native 侧逻辑时使用。

1시간 설치 수
1
GitHub Stars
137
업데이트
8월 10일