Loading...
Loading...
Kuikly Exposure & Visibility Event Development Assistant (Kuikly DSL). It guides how to use five visibility events including didAppear, didDisappear, willAppear, willDisappear, and appearPercentage to implement functions such as component exposure reporting, visibility percentage monitoring, list item exposure statistics, etc. It is used when users need to implement scenarios like exposure reporting, visibility monitoring, list item exposure statistics, visibility percentage calculation in Kuikly.
npx skill4agent add tencent-tds/kuiklyui-ai kuikly-visibility-exposureComponent → parent → ... → ScrollerView（Scroller/List/WaterfallList/PageList）→ Hit
→ ModalView → Hit
→ Pager → Hit (fallback)Important: Visibility is relative to the visible area of the nearest scroll container, not the screen position. If screen position visibility is required, especially in nested scroll container scenarios, you can use the scroll event callback of the outer scroll container and calculate the real position of the node combined with the list offset.
┌──────────────────────────────────────────────┐
│ │
▼ │
DID_DISAPPEAR ──→ WILL_APPEAR ──→ DID_APPEAR ──→ WILL_DISAPPEAR ─┘
(Completely Invisible) (Partially Visible) (Fully Visible) (Partially Visible)| Spatial Relationship | Judgment Condition | State Transition |
|---|---|---|
| Disjoint (Component is completely outside the window) | No intersection between component frame and window | → WILL_DISAPPEAR → DID_DISAPPEAR |
| Contained (Component is completely inside the window) | Component frame is fully within the window | → WILL_APPEAR → DID_APPEAR |
| Intersecting (Component is partially inside the window) | Partial overlap between component frame and window | From DID_DISAPPEAR → WILL_APPEAR; From DID_APPEAR → WILL_DISAPPEAR |
addNextTickTask| Event | Description | Callback Parameters | import |
|---|---|---|---|
| Component is about to become visible (partially enters the window) | None | |
| Component is fully visible (completely inside the window) | None | |
| Component is about to become invisible (partially leaves the window) | None | |
| Component is completely invisible (completely outside the window) | None | |
| Component visibility percentage changes | | |
| Spatial Relationship | percentage Value |
|---|---|
| Completely Invisible (Disjoint) | 0 |
| Fully Visible (Contained) | 1 |
| Partially Visible (Intersecting) | Vertical List: |
The percentage value is always clamped to the [0, 1] range. The callback is only triggered when the percentage changes.
| Property | Description | Parameter Type | Supported Containers |
|---|---|---|---|
| Cut off the specified height from the top of the visible window | Float | Scroller, List, WaterfallList |
| Cut off the specified height from the bottom of the visible window | Float | Scroller, List, WaterfallList |
Working Principle: Reduce the "visibility judgment window" of the list. After setting, visible window height = list height - marginTop - marginBottom, and the child component Y coordinate will also subtract marginTop. For example, if the list height is 500dp, after settingandvisibleAreaIgnoreTopMargin(60f), only child components within the middle 360dp area of the list will be judged as visible.visibleAreaIgnoreBottomMargin(80f)Typical Scenario: Fixed occluding UI at the top/bottom of the list (such as floating navigation bar, translucent mask, bottom toolbar). Although child components in the occluded area are "visible" in the list coordinate system, users cannot actually see them, so they need to be excluded from exposure judgment.
import com.tencent.kuikly.core.base.event.didAppear
View {
attr {
size(100f, 100f)
backgroundColor(Color.GREEN)
}
event {
didAppear {
// Component is fully visible, execute exposure reporting
}
}
}import com.tencent.kuikly.core.base.event.appearPercentage
View {
attr {
size(100f, 100f)
backgroundColor(Color.GREEN)
}
event {
appearPercentage { percentage01 ->
// percentage01 is the visibility percentage in [0,1]
// 1 means 100% visible, 0 means 0% visible
if (percentage01 >= 0.5f) {
// Execute logic when visibility exceeds 50%
}
}
}
}import com.tencent.kuikly.core.base.event.willAppear
import com.tencent.kuikly.core.base.event.didAppear
import com.tencent.kuikly.core.base.event.willDisappear
import com.tencent.kuikly.core.base.event.didDisappear
import com.tencent.kuikly.core.base.event.appearPercentage
View {
event {
willAppear {
// Component is about to become visible (partially enters the window)
}
didAppear {
// Component is fully visible → Execute exposure reporting
}
willDisappear {
// Component is about to become invisible (partially leaves the window)
}
didDisappear {
// Component is completely invisible
}
appearPercentage { percentage ->
// Visibility percentage changes
}
}
}import com.tencent.kuikly.core.base.event.didAppear
Scroller {
attr {
flex(1f)
// Child components in the top 60dp area do not participate in exposure judgment
visibleAreaIgnoreTopMargin(60f)
// Child components in the bottom 80dp area do not participate in exposure judgment
visibleAreaIgnoreBottomMargin(80f)
}
View {
attr {
height(120f)
backgroundColor(Color(0xFFE3F2FD))
}
event {
didAppear {
// Only triggered when fully entering the middle valid area (500 - 60 - 80 = 360dp)
}
}
}
}| Wrong Practice | Correct Practice | Reason |
|---|---|---|
❌ Use | ✅ Use page lifecycle | The root node has no scroll container as visible window, behavior is unpredictable |
| ❌ Assume visibility is relative to screen position | ✅ Visibility is relative to the visible area of the nearest scroll container | For screen position visibility, calculate with scroll event offset |
❌ Directly execute exposure reporting in | ✅ Use | |
| ❌ Forget to import visibility event extension functions | ✅ Add corresponding import statements | These are extension functions of |