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

Contents [Core Guidelines]( core guidelines) [Workflow: Creating Expand View (Kuikly Side)]( workflow creating expand view kuikly side) [Workflow: Implementing Native Side View]( workflow implementing native side view) 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 类 Step 2: 定义 Attr 类 Attr 表示组件支持的属性集。 Step 3: 定义 Event 类 Event 表示组件支持的事件。 Step 4: 组件方法（可选）组件方法是 Kuikly 侧暴露的 API，实际实现在 Native 侧。 ⚠️ 注意： View 的方法支持异步回调结果，即 renderView?.callMethod("method", "params", callback) ，但不支持同步返回结果。 View 方法不支持传递二进制数据，如需传输图片等二进制内容，请通过 Base64 编码后以 JSON 形式传递，或使用 Module 方法实现。 Step 5: 编写声明式 API Step 6: 业务使用使用 ViewRef 获取组件引用通过 ViewRef 可以获取组件实例，在 Pager 其他位置调用组件方法。 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](references/VIEW IMPLEMENT.md) 速查：各平台 View 基类与注册方式平台基类/协议注册方式注意事项 Android IKuiklyRenderViewExport registerExternalRenderView 中 renderViewExport(name) { View(ctx) } 继承原生 View 并实现接口 iOS KuiklyRenderViewExportProtocol 类名必须与 viewName 一致（运行时动态创建）属性方法命名 setCss xxx ，方法命名 css xxx 鸿蒙 (ArkTS) KuiklyRenderBaseView getCustomRenderViewCreatorRegisterMap 或 getCustomRenderViewCreatorRegisterMapV2 中注册需实现 createArkUIView() 返回 ComponentContent H5 IKuiklyRenderViewExport registerExternalRenderView 中 renderViewExport(name) { View() } 重写 ele 属性返回 DOM 元素小程序 IKuiklyRenderViewExport registerExternalRenderView + Transform.addComponentsAlias + base.wxml 模板需创建 MiniXxxElement 并配置模板 Native 侧 setProp 支持的数据类型 Kuikly 侧类型 Native 侧接收类型 String String / NSString Int / Float / Double 对应基础类型 / NSNumber Boolean Boolean / BOOL Event 回调 KuiklyRenderCallback 事件触发机制在 Native 侧，事件通过 KuiklyRenderCallback 回调给 Kuikly 侧：常见陷阱与正确做法 ❌ 错误做法 ✅ 正确做法 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 之外调用 renderView View 方法必须在 performTaskWhenRenderViewDidLoad 回调中调用

kuikly-expand-view