Kuikly 响应式更新与指令系统
核心机制
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<String>() // 响应式列表，配合 vfor
var tags by observableSet<String>() // 响应式集合绑定到 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 更新规则等