tencent-tds/kuiklyui-ai

kuikly-visibility-exposure

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

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/tencent-tds/kuiklyui-ai --skill kuikly-visibility-exposure

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

Kuikly 曝光与可见性事件

核心概念

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

  1. 可见窗口:最近的滚动容器(Scroller/List/WaterfallList)、ModalView 或 Pager
  2. 可见性状态:四种状态 + 百分比(WILLAPPEAR → DIDAPPEAR → WILLDISAPPEAR → DIDDISAPPEAR)
  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 与窗口无交集→ WILLDISAPPEAR → DIDDISAPPEAR
包含(组件完全在窗口内)组件 frame 完全在窗口内→ WILLAPPEAR → DIDAPPEAR
相交(组件部分在窗口内)组件 frame 与窗口部分重叠从 DIDDISAPPEAR → WILLAPPEAR;从 DIDAPPEAR → WILLDISAPPEAR

特殊行为:

  • 组件被移除(v-if 移除、页面销毁等)时,会自动触发 WILLDISAPPEAR → DIDDISAPPEAR,并将 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

z tego samego repozytorium

Więcej Skills

Wszystkie Skills
tencent-tds
Społeczność

kuikly-animation

Kuikly DSL 动画开发助手(Kuikly DSL)。指导使用声明式和命令式两种方式实现 transform、opacity、backgroundColor、frame 等属性动画,涵盖串行/并行编排与动画取消。当用户需要实现动画效果时使用。

Instalacje / 1h
1
GitHub Stars
137
Aktualizacja
10 sie
tencent-tds
Społeczność

kuikly-compose-interop-dsl

Compose DSL 混用 Kuikly DSL 完整开发助手。指导如何在 Compose DSL 页面中嵌入 Kuikly DSL 组件(DeclarativeBaseView / ViewContainer)及在 Compose 中调用 Kuikly Module。当用户需要在 Compose 页面中复用 Kuikly DSL 组件、封装原生 View 为 Composable、在 Compose 中调用 Kuikly Module时使用。

Instalacje / 1h
1
GitHub Stars
137
Aktualizacja
10 sie
tencent-tds
Społeczność

kuikly-coroutines-threading

Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程,包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。

Instalacje / 1h
1
GitHub Stars
137
Aktualizacja
10 sie
tencent-tds
Społeczność

kuikly-expand-api

Kuikly 自定义 Module 开发助手。指导如何创建自定义 Module,扩展原声API。覆盖完整开发流程:Kuikly 侧 Module 定义、Pager/ComposeContainer 注册、各平台 Native 侧实现、Module 注册,及使用。当用户需要自定义 Module、扩展原生 API、实现 Kuikly 与 Native 双向通信、在各平台实现 Module 的 Native 侧逻辑时使用。

Instalacje / 1h
1
GitHub Stars
137
Aktualizacja
10 sie