<< All versions

Skill v1.0.0

currentAutomated scan100/100
tencent-tds/kuiklyui-ai/kuikly-visibility-exposure
──Details
PublishedOctober 27, 2026 at 08:48 PM
Content Hashsha256:0ef1cc874ed0648b...
Git SHAaf4e8ee8ae0c
──Files
Files (1 file, 8.4 KB)
SKILL.md8.4 KBactive
SKILL.md · 211 lines · 8.4 KB

name: kuikly-visibility-exposure description: Kuikly 曝光与可见性事件开发助手(Kuikly DSL)。指导如何使用 didAppear、didDisappear、willAppear、willDisappear、appearPercentage 五种可见性事件实现组件曝光上报、可见百分比监听、列表项曝光统计等功能。当用户在 Kuikly 中需要实现曝光上报、可见性监听、列表项曝光统计、可见百分比计算等场景时使用。 metadata: version: "1.0.0"

Kuikly 曝光与可见性事件

核心概念

Kuikly 提供了一套完整的组件可见性事件系统，用于监听组件在滚动容器或页面中的可见状态变化。四大要素：

  1. 可见窗口：最近的滚动容器（Scroller/List/WaterfallList）、ModalView 或 Pager
  2. 可见性状态：四种状态 + 百分比（WILL_APPEAR → DID_APPEAR → WILL_DISAPPEAR → DID_DISAPPEAR）
  3. 触发时机：滚动偏移变化、子视图布局完成、可见区域 margin 变化、组件被移除
  4. 应用场景：曝光上报、懒加载、播放控制、可见百分比监听

可见窗口查找规则

系统从组件的 parent 开始向上遍历，找到第一个匹配的祖先作为可见窗口：

组件 → parent → ... → ScrollerView（Scroller/List/WaterfallList/PageList）→ 命中
                     → ModalView → 命中
                     → Pager → 命中（兜底）
  • 对于 ScrollerView（Scroller/List/WaterfallList）：可见性基于列表可见区域计算，会减去滚动偏移量
  • 对于 ModalView：可见性基于 Modal 的布局 frame 计算
  • 对于 Pager：可见性基于页面的布局 frame 计算
重要：可见性是相对于最近滚动容器的可见区域，而非屏幕位置。若需屏幕位置可见性，如果嵌套滚动容器场景，可使用外层滚动容器的 scroll 事件回调，结合列表偏移量计算节点真实位置。

状态机

                    ┌──────────────────────────────────────────────┐
                    │                                              │
                    ▼                                              │
  DID_DISAPPEAR ──→ WILL_APPEAR ──→ DID_APPEAR ──→ WILL_DISAPPEAR ─┘
  (完全不可见)       (部分可见)       (完全可见)       (部分可见)

三种空间关系与状态转换：

空间关系判定条件状态转换
相离（组件完全在窗口外）组件 frame 与窗口无交集→ WILL_DISAPPEAR → DID_DISAPPEAR
包含（组件完全在窗口内）组件 frame 完全在窗口内→ WILL_APPEAR → DID_APPEAR
相交（组件部分在窗口内）组件 frame 与窗口部分重叠从 DID_DISAPPEAR → WILL_APPEAR；从 DID_APPEAR → WILL_DISAPPEAR

特殊行为：

  • 组件被移除（v-if 移除、页面销毁等）时，会自动触发 WILL_DISAPPEAR → DID_DISAPPEAR，并将 percentage 置为 0
  • 状态变更是异步的（通过 addNextTickTask 调度），页面销毁时除外（同步执行）

API 速查

可见性事件

事件描述回调参数import
willAppear { }组件将要可见（部分进入窗口）无com.tencent.kuikly.core.base.event.willAppear
didAppear { }组件完全可见（完全在窗口内）无com.tencent.kuikly.core.base.event.didAppear
willDisappear { }组件将要不可见（部分离开窗口）无com.tencent.kuikly.core.base.event.willDisappear
didDisappear { }组件完全不可见（完全在窗口外）无com.tencent.kuikly.core.base.event.didDisappear
appearPercentage { }组件可见百分比变化percentage01: Float（[0,1]）com.tencent.kuikly.core.base.event.appearPercentage

appearPercentage 百分比计算逻辑

空间关系percentage 值
完全不可见（相离）0
完全可见（包含）1
部分可见（相交）纵向列表：可见高度 / 组件高度；横向列表（FlexDirection.ROW / ROW_REVERSE）：可见宽度 / 组件宽度
percentage 值始终被 clamp 到 [0, 1] 范围内。只有当 percentage 发生变化时才会触发回调。

Scroller/List/WaterfallList 辅助属性

属性描述参数类型支持的容器
visibleAreaIgnoreTopMargin(margin)从可见窗口顶部裁掉指定高度FloatScroller、List、WaterfallList
visibleAreaIgnoreBottomMargin(margin)从可见窗口底部裁掉指定高度FloatScroller、List、WaterfallList
作用原理：缩小列表的"可见性判定窗口"。设置后，可见窗口高度 = 列表高度 - marginTop - marginBottom，子组件 Y 坐标也会减去 marginTop。例如列表高度 500dp，设置 visibleAreaIgnoreTopMargin(60f) 和 visibleAreaIgnoreBottomMargin(80f) 后，只有列表中间 360dp 区域内的子组件才会被判定为可见。
典型场景：列表顶部/底部有固定遮挡 UI（如悬浮导航栏、半透明蒙层、底部工具栏），被遮挡区域内的子组件虽然在列表坐标系内"可见"，但实际上用户看不到，需要从曝光判定中排除。

快速入门

didAppear 曝光上报

kotlin
import com.tencent.kuikly.core.base.event.didAppear
 
View {
    attr {
        size(100f, 100f)
        backgroundColor(Color.GREEN)
    }
    event {
        didAppear {
            // 组件完全可见，执行曝光上报
        }
    }
}

appearPercentage 可见百分比监听

kotlin
import com.tencent.kuikly.core.base.event.appearPercentage
 
View {
    attr {
        size(100f, 100f)
        backgroundColor(Color.GREEN)
    }
    event {
        appearPercentage { percentage01 ->
            // percentage01 为 [0,1] 的露出百分比
            // 1 表示 100% 可见，0 表示 0% 可见
            if (percentage01 >= 0.5f) {
                // 超过 50% 可见时执行逻辑
            }
        }
    }
}

完整生命周期监听

kotlin
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 {
            // 组件将要可见（部分进入窗口）
        }
        didAppear {
            // 组件完全可见 → 曝光上报
        }
        willDisappear {
            // 组件将要不可见（部分离开窗口）
        }
        didDisappear {
            // 组件完全不可见
        }
        appearPercentage { percentage ->
            // 可见百分比变化
        }
    }
}

visibleAreaIgnoreMargin 排除遮挡区域

kotlin
import com.tencent.kuikly.core.base.event.didAppear
 
Scroller {
    attr {
        flex(1f)
        // 顶部 60dp 区域内的子组件不参与曝光判定
        visibleAreaIgnoreTopMargin(60f)
        // 底部 80dp 区域内的子组件不参与曝光判定
        visibleAreaIgnoreBottomMargin(80f)
    }
 
    View {
        attr {
            height(120f)
            backgroundColor(Color(0xFFE3F2FD))
        }
        event {
            didAppear {
                // 只有完全进入中间有效区域（500 - 60 - 80 = 360dp）时才触发
            }
        }
    }
}

常见错误与陷阱

错误做法正确做法原因
❌ 根节点使用 didAppear 监听页面曝光✅ 使用页面生命周期 pageDidAppear()根节点没有滚动容器作为可见窗口，行为不可预期
❌ 认为可见性是相对于屏幕位置✅ 可见性是相对于最近滚动容器的可见区域需要屏幕位置请结合 scroll 事件偏移量计算
❌ 在 appearPercentage 中直接执行曝光上报✅ 曝光上报用 didAppear，或加阈值 + 去重标记appearPercentage 每次滚动都触发，频率极高
❌ 忘记 import 可见性事件扩展函数✅ 添加对应的 import 语句这些是 Event 的扩展函数，需要显式 import

完整使用案例

见 EXAMPLES.md

All versions