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 ─┘
  (完全不可见)       (部分可见)       (完全可见)       (部分可见)

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

特殊行为：

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

API 速查

可见性事件

appearPercentage 百分比计算逻辑

percentage 值始终被 clamp 到 [0, 1] 范围内。只有当 percentage 发生变化时才会触发回调。

Scroller/List/WaterfallList 辅助属性

作用原理：缩小列表的"可见性判定窗口"。设置后，可见窗口高度 = 列表高度 - marginTop - marginBottom，子组件 Y 坐标也会减去 marginTop。例如列表高度 500dp，设置 visibleAreaIgnoreTopMargin(60f) 和 visibleAreaIgnoreBottomMargin(80f) 后，只有列表中间 360dp 区域内的子组件才会被判定为可见。

典型场景：列表顶部/底部有固定遮挡 UI（如悬浮导航栏、半透明蒙层、底部工具栏），被遮挡区域内的子组件虽然在列表坐标系内"可见"，但实际上用户看不到，需要从曝光判定中排除。

快速入门

didAppear 曝光上报

import com.tencent.kuikly.core.base.event.didAppear

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

appearPercentage 可见百分比监听

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% 可见时执行逻辑
            }
        }
    }
}

完整生命周期监听

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 排除遮挡区域

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）时才触发
            }
        }
    }
}

常见错误与陷阱

完整使用案例

见 [EXAMPLES.md](references/EXAMPLES.md)