kuikly-reactive-observer

Kuikly 响应式更新与指令系统开发助手（Kuikly DSL），用于指导开发者使用响应式字段与指令系统实现 UI 的自动更新。

一、核心机制在 attr {} 闭包中读取响应式字段时，框架自动收集依赖；字段值变化时，自动更新绑定的 UI 属性。只需更新数据，UI 自动响应。注意：observable 内部使用 == 比较新旧值，相等时不触发更新。

二、响应式字段声明在 Pager（实现了 PagerScope 接口）或任何 PagerScope 子类中使用，推荐使用 PagerScope 扩展函数：

import com.tencent.kuikly.core.reactive.handler.observable import com.tencent.kuikly.core.reactive.handler.observableList import com.tencent.kuikly.core.reactive.handler.observableSet

var counter by observable(0) // 单值 var list by observableList() // 响应式列表，配合 vfor var tags by observableSet() // 响应式集合

绑定到 UI 示例：

var title by observable("Hello")

Text { attr { text(ctx.title) // 直接引用响应式字段，自动绑定 } } // 更新 ctx.title = "World" 后，Text 自动刷新

三、指令系统

循环指令 vfor / vforIndex

var list by observableList<String>()

// vfor：遍历 observableList，增删时自动增量更新 List { attr { flex(1f) } vfor({ ctx.list }) { item -> Text { attr { text(item) } } } }

// vforIndex：额外提供 index 和 count vforIndex({ ctx.list }) { item, index, count -> View { attr { backgroundColor(if (index % 2 == 0) Color.GRAY else Color.TRANSPARENT) } Text { attr { text("$index: $item") } } } }

必须传闭包 { ctx.list }，不是直接传值 ctx.list。

循环指令 vforLazy（超大列表）仅在 ListView 中使用（不含 PageList、WaterfallList），动态增删可见范围外的虚拟节点：

List { attr { flex(1f) } vforLazy({ ctx.list }, maxLoadItem = 50) { item, index, count -> Text { attr { text(item) } } } }

参数说明：

itemList：类型 () -> ObservableList<T>，数据源闭包。
maxLoadItem：类型 Int，默认值 30，内存中最大虚拟节点数，建议为一屏可见数的 2~3 倍。
itemCreator：类型 (T, Int, Int) -> Unit，构建闭包。

条件指令 vif / velseif / velse

var state by observable(0)

View { vif({ ctx.state == 1 }) { Text { attr { text("状态1") } } } velseif({ ctx.state == 2 }) { View { attr { size(100f, 100f); backgroundColor(Color.GREEN) } } } velse { Text { attr { text("其他状态") } } } }

velseif / velse 必须紧跟 vif 或 velseif，中间不能插入其他组件。

绑定指令 vbind 类似 when 语句，绑定值变化时移除所有子组件并重建：

var state by observable(0)

View { vbind({ ctx.state }) { when (ctx.state) { 1 -> Text { attr { text("状态1") } } 2 -> View { attr { size(100f, 100f); backgroundColor(Color.GREEN) } } } } }

vbind 绑定值为 null 时不执行 creator 闭包。

四、高效更新列表：diffUpdate

// 基本用法（基于 Myers diff 算法，只增删变化的 Item） list.diffUpdate(newData)

// 自定义比较（通过 id 判断是否同一元素） userList.diffUpdate(newUsers) { old, new -> old.id == new.id }

性能对比：

clear() + addAll()：销毁所有 Item → 重建，性能差。
diffUpdate(newList)：只增删变化的 Item，性能优。

五、常见错误与约束规则参考文件包括：

COMMON_MISTAKES.md：涵盖响应式依赖断开、对象内部属性修改不触发更新、vfor 闭包传值而非传闭包、ViewBuilder 未 invoke 等 8 类典型错误。
DIRECTIVE_RULES.md：涵盖 vfor 闭包必须且仅生成一个根节点、根节点不能是指令节点、vforLazy 仅限 ListView、velseif/velse 必须紧跟 vif、vforIndex 的 index/count 更新规则等。

适用场景：使用 Kuikly DSL 进行响应式 UI 开发、列表渲染与条件渲染、超大列表懒加载、列表高效增量更新等。限制：vforLazy 仅限 ListView 使用；velseif/velse 必须紧跟 vif 或 velseif；vfor 必须传闭包而非直接传值。

技能介绍