メニュー
Kuikly 曝光与可见性事件开发助手(Kuikly DSL)。指导如何使用 didAppear、didDisappear、willAppear、willDisappear、appearPercentage 五种可见性事件实现组件曝光上报、可见百分比监听、列表项曝光统计等功能。当用户在 Kuikly 中需要实现曝光上报、可见性监听、列表项曝光统计、可见百分比计算等场景时使用。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | kuikly-visibility-exposure |
| description | Kuikly 曝光与可见性事件开发助手(Kuikly DSL)。指导如何使用 didAppear、didDisappear、willAppear、willDisappear、appearPercentage 五种可见性事件实现组件曝光上报、可见百分比监听、列表项曝光统计等功能。当用户在 Kuikly 中需要实现曝光上报、可见性监听、列表项曝光统计、可见百分比计算等场景时使用。 |
Kuikly 提供了一套完整的组件可见性事件系统，用于监听组件在滚动容器或页面中的可见状态变化。四大要素：
系统从组件的 parent 开始向上遍历，找到第一个匹配的祖先作为可见窗口：
组件 → parent → ... → ScrollerView（Scroller/List/WaterfallList/PageList）→ 命中
→ ModalView → 命中
→ Pager → 命中（兜底）
重要：可见性是相对于最近滚动容器的可见区域，而非屏幕位置。若需屏幕位置可见性，如果嵌套滚动容器场景，可使用外层滚动容器的 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 |
特殊行为：
addNextTickTask 调度），页面销毁时除外（同步执行）| 事件 | 描述 | 回调参数 | 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 |
| 空间关系 | percentage 值 |
|---|---|
| 完全不可见（相离） | 0 |
| 完全可见（包含） | 1 |
| 部分可见（相交） | 纵向列表：可见高度 / 组件高度；横向列表（FlexDirection.ROW / ROW_REVERSE）：可见宽度 / 组件宽度 |
percentage 值始终被 clamp 到 [0, 1] 范围内。只有当 percentage 发生变化时才会触发回调。
| 属性 | 描述 | 参数类型 | 支持的容器 |
|---|---|---|---|
visibleAreaIgnoreTopMargin(margin) | 从可见窗口顶部裁掉指定高度 | Float | Scroller、List、WaterfallList |
visibleAreaIgnoreBottomMargin(margin) | 从可见窗口底部裁掉指定高度 | Float | Scroller、List、WaterfallList |
作用原理：缩小列表的"可见性判定窗口"。设置后，可见窗口高度 = 列表高度 - marginTop - marginBottom，子组件 Y 坐标也会减去 marginTop。例如列表高度 500dp，设置
visibleAreaIgnoreTopMargin(60f)和visibleAreaIgnoreBottomMargin(80f)后，只有列表中间 360dp 区域内的子组件才会被判定为可见。典型场景：列表顶部/底部有固定遮挡 UI（如悬浮导航栏、半透明蒙层、底部工具栏），被遮挡区域内的子组件虽然在列表坐标系内"可见"，但实际上用户看不到，需要从曝光判定中排除。
import com.tencent.kuikly.core.base.event.didAppear
View {
attr {
size(100f, 100f)
backgroundColor(Color.GREEN)
}
event {
didAppear {
// 组件完全可见，执行曝光上报
}
}
}
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 ->
// 可见百分比变化
}
}
}
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 |
Analyze KuiklyUI Compose DSL recomposition performance issues from Recomposition Profiler output. Use when the user mentions 重组分析、重组优化、卡顿分析、recomp 报告、recomposition analysis, or asks to analyze profiler_report.json / profiler_frames.jsonl log files generated by KuiklyUI Recomposition Profiler.
Kuikly UI 框架开发助手。帮助使用 Kuikly 组件（View、Text、Button、List、Image、Modal、ActionSheet、Input、Scroller、Tabs 等 UI 组件）和模块（Router、Network、SP、Notify 等系统模块），自动提供正确的 import 语句、API 使用方法和完整代码示例。支持传统 Kuikly DSL（attr/event）和 Compose DSL 两种开发方式。适用场景：Kuikly 页面开发、组件使用、布局实现、事件处理、FlexBox 布局、响应式状态管理、动画效果、页面路由跳转、网络请求、列表渲染、自定义组件/模块扩展、Kuikly 编码问题、KuiklyUI 开发。
Kuikly DSL 动画开发助手(Kuikly DSL)。指导使用声明式和命令式两种方式实现 transform、opacity、backgroundColor、frame 等属性动画，涵盖串行/并行编排与动画取消。当用户需要实现动画效果时使用。
Kuikly 资源文件管理与加载助手。指导如何在 Kuikly 中添加、打包和加载 assets 资源，包括目录结构规范（common/页面资源）、各平台打包配置（Android/iOS/鸿蒙/H5/微信小程序/动态化）、ImageUri API 使用。当用户需要在 Kuikly 中使用本地图片资源、配置 assets 打包时使用。
Compose DSL 混用 Kuikly DSL 完整开发助手。指导如何在 Compose DSL 页面中嵌入 Kuikly DSL 组件（DeclarativeBaseView / ViewContainer)及在 Compose 中调用 Kuikly Module。当用户需要在 Compose 页面中复用 Kuikly DSL 组件、封装原生 View 为 Composable、在 Compose 中调用 Kuikly Module时使用。
Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程，包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。