Compose 中的可见性跟踪

跟踪界面元素何时在屏幕上可见，对于各种应用场景都很有帮助，例如记录分析数据、管理界面状态，以及通过自动播放或暂停视频内容来优化资源。Compose 提供了多个修饰符来跟踪界面元素的可见性，例如：

  • onVisibilityChanged - 此修饰符会在可组合项的可见性发生变化时通知您。它非常适合在每次可组合项变为可见时触发操作或副作用。
  • onLayoutRectChanged - 此修饰符提供有关可组合项相对于根、窗口和屏幕的边界的信息。它提供低级控制，是 onVisibilityChanged 的基础 API。该修饰符与 onGloballyPositioned 类似，但性能更出色，灵活性更高。

您可以将这些 API 与任何可组合项搭配使用，作为修饰符链的一部分。

使用 onVisibilityChanged 跟踪可见性变化

了解某个项何时对用户可见或部分可见，有助于您跟踪分析数据（例如观看次数）、优化性能（仅在项可见时从网络提取或预提取数据），甚至触发事件（播放或暂停视频）。

如需在项的可见性发生变化时收到通知，请使用 onVisibilityChanged 修饰符，如以下示例所示：

Text(
    text = "Some text",
    modifier = Modifier
        .onVisibilityChanged { visible ->
            if (visible) {
                // Do something if visible
            } else {
                // Do something if not visible
            }
        }
        .padding(vertical = 8.dp)
)

onVisibilityChanged 修饰符提供一个布尔值，用于反映可组合项的当前可见性状态。此外，它还提供 minFraction 和 minDurationMs 等参数，让您能够更精细地控制何时需要触发可见性回调。

与所有其他修饰符一样，onVisibilityChanged 修饰符的顺序也很重要。上面的示例展示了一个可组合函数，该函数可呈现带有内边距的文本。为确保修饰符影响整个可组合项以及内边距，请在 padding 修饰符之前添加 onVisibilityChanged 修饰符。

在触发可见性回调之前，为可组合项设置时间限制

在某些情况下，您可能希望仅在某项内容对用户可见达到一定时长后才触发操作。例如，如果视频已向用户展示一段时间，您可以自动播放该视频。

如需在某个项可见达到指定时长后触发操作，请使用 onVisibilityChanged 修饰符中的 minDurationMs 参数。此参数指定可组合项需要持续可见的最短时间，以便触发回调。如果可组合项在达到时长之前停止显示，计时器会重置。默认值为 0 毫秒。

以下代码段会在可组合项对用户可见 3 秒后将背景更改为紫色：

var background by remember { mutableStateOf(PalePink) }
Card(
    modifier = modifier
        // ...
        .onVisibilityChanged(minDurationMs = 3000) {
            if (it) {
                background = MutedPlum
            }
        }
) {

    Box(
        modifier = Modifier
            // ...
            .background(background),
        contentAlignment = Alignment.Center,
    ) {
        // ...
    }
}

图 1. 可组合项在屏幕上连续显示 3 秒后，背景会从粉色变为梅红色。

设置最小可见比例

在处理可滚动内容（例如 LazyColumn）时，为可组合项的可见性回调设置最小可见比例非常有用，这有助于优化超出屏幕尺寸的项的数据提取。

在这种情况下，请使用 onVisibilityChanged 修饰符中的 minFractionVisible 参数来定义需要显示在屏幕上的比例，以便将可组合项标记为可见。它支持 0.0f 到 1.0f 之间的浮点值，默认设置为 1.0f。 1.0f 表示可组合项需要完全显示在屏幕上，才能触发回调。

LazyColumn(
    modifier = modifier.fillMaxSize()
) {
    item {
        Box(
            modifier = Modifier
                // ...
                // Here the visible callback gets triggered when 20% of the composable is visible
                .onVisibilityChanged(
                    minFractionVisible = 0.2f,
                ) { visible ->
                    if (visible) {
                        // Call specific logic here
                        // viewModel.fetchDataFromNetwork()
                    }
                }
                .padding(vertical = 16.dp)
        ) {
            Text(
                text = "Sample Text",
                modifier = Modifier.padding(horizontal = 16.dp)
            )
        }
    }
}

图 2. 未设置 minFractionVisible。 图 3. minFractionVisible 设置为 0.2f。

前面使用的示例会在可组合项完全可见之前，从网络预加载 Androidify 机器人。在图 2 中，第三个机器人未加载，因为可组合项未完全可见。在图 3 中，minFractionVisible 已设置，第三个机器人会在完全显示在屏幕上之前加载。

上一页
固有特性测量