kuikly-reactive-observer

Original：🇨🇳 Chinese

Translated

Kuikly Reactive Update and Directive System Development Assistant (Kuikly DSL). Guides on how to implement UI reactive updates using observable, observableList, observableSet, and the correct usage of directives such as vfor, vforIndex, vforLazy, vif, velseif, velse, vbind. Use this when you need to handle the following scenarios in Kuikly: (1) Declare reactive fields and bind them to UI attributes (2) List rendering (vfor/vforIndex/vforLazy) (3) Conditional rendering (vif/velseif/velse) (4) Value binding rendering (vbind) (5) Efficient list updates (diffUpdate) (6) Troubleshooting issues like reactive data not taking effect or UI not updating (7) CRUD operations on observableList/observableSet (8) Reactive update strategies for complex objects

3installs

Sourcetencent-tds/kuiklyui-ai

Added on2026-04-22

NPX Install

npx skill4agent add tencent-tds/kuiklyui-ai kuikly-reactive-observer

SKILL.md Content (Chinese)

View Translation Comparison →

Kuikly Reactive Update and Directive System

Core Mechanism

When reading reactive fields in the

attr {}

closure, the framework automatically collects dependencies; when the field value changes, the bound UI attributes are updated automatically. Just update the data, and the UI responds automatically.

Note:
observable
uses
==
internally to compare old and new values, no update is triggered when values are equal.

Reactive Field Declaration

Use in

Pager

(which implements the

PagerScope

interface) or any subclass of

PagerScope

:

kotlin

// Recommended: PagerScope extension function
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)                    // Single value
var list by observableList<String>()            // Reactive list, used with vfor
var tags by observableSet<String>()             // Reactive set

Bind to UI

kotlin

var title by observable("Hello")

Text {
    attr {
        text(ctx.title) // Directly reference the reactive field, automatic binding
    }
}
// After updating ctx.title = "World", Text refreshes automatically

Directive System

Loop Directives: vfor / vforIndex

kotlin

var list by observableList<String>()

// vfor: Traverse observableList, automatic incremental update when adding or deleting items
List {
    attr { flex(1f) }
    vfor({ ctx.list }) { item ->
        Text { attr { text(item) } }
    }
}

// vforIndex: Provides additional index and count
vforIndex({ ctx.list }) { item, index, count ->
    View {
        attr { backgroundColor(if (index % 2 == 0) Color.GRAY else Color.TRANSPARENT) }
        Text { attr { text("$index: $item") } }
    }
}

Must pass a closure
{ ctx.list }
, not directly pass the value
ctx.list
.

Loop Directive: vforLazy (Large Lists)

Only used in

ListView

(excluding PageList, WaterfallList), dynamically adds or removes virtual nodes outside the visible range:

kotlin

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

Parameter	Type	Default Value	Description
itemList	`() -> ObservableList<T>`	—	Data source closure
maxLoadItem	`Int`	30	Maximum number of virtual nodes in memory, recommended to be 2~3 times the number of visible items on one screen
itemCreator	`(T, Int, Int) -> Unit`	—	Builder closure

Conditional Directives: vif / velseif / velse

kotlin

var state by observable(0)

View {
    vif({ ctx.state == 1 }) {
        Text { attr { text("State 1") } }
    }
    velseif({ ctx.state == 2 }) {
        View { attr { size(100f, 100f); backgroundColor(Color.GREEN) } }
    }
    velse {
        Text { attr { text("Other States") } }
    }
}

velseif
/
velse
must immediately follow
vif
or
velseif
, no other components can be inserted in between.

Binding Directive: vbind

Similar to the

when

statement, removes all child components and rebuilds them when the bound value changes:

kotlin

var state by observable(0)

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

When the bound value of
vbind
is
null
, the creator closure is not executed.

Efficient List Updates: diffUpdate

kotlin

// Basic usage (based on Myers diff algorithm, only adds/deletes changed Items)
list.diffUpdate(newData)

// Custom comparison (judge if it's the same element via id)
userList.diffUpdate(newUsers) { old, new -> old.id == new.id }

Method	Behavior	Performance
`clear() + addAll()`	Destroys all Items → Rebuilds	Poor
`diffUpdate(newList)`	Only adds/deletes changed Items	Excellent

Common Errors and Constraint Rules

See the following reference documents:

Common Errors: COMMON_MISTAKES.md — 8 typical errors including broken reactive dependencies, internal object property modifications not triggering updates, passing values instead of closures in vfor, ViewBuilder not being invoked, etc.
Directive Constraint Rules: DIRECTIVE_RULES.md — Rules such as vfor closures must generate exactly one root node, root node cannot be a directive node, vforLazy is limited to ListView, velseif/velse must follow vif immediately, update rules for index/count in vforIndex, etc.

kuikly-reactive-observer

NPX Install

Tags

SKILL.md Content (Chinese)

Kuikly Reactive Update and Directive System

Core Mechanism

Reactive Field Declaration

Bind to UI

Directive System

Loop Directives: vfor / vforIndex

Loop Directive: vforLazy (Large Lists)

Conditional Directives: vif / velseif / velse

Binding Directive: vbind

Efficient List Updates: diffUpdate

Common Errors and Constraint Rules