📚 课程目录第4章 LazyStaggeredGrid与瀑布流按需加载

4. LazyStaggeredGrid 与瀑布流按需加载：不规则子项复用、索引对齐、滚动抖动处理

4.1 原理：不规则子项的复用与对齐

LazyStaggeredGrid 是 Compose 中为瀑布流（Masonry）场景提供的按需加载容器。与 LazyVerticalGrid 固定网格不同，它允许每个子项跨越不同数量的栅格列（span），从而实现高度/宽度不规则的排列。其核心原理包括：

片段化复用：网格被切分为多个“片段”（staggered segment），每个片段内部维护独立的子项缓存和复用池。不同跨度的子项不会混入同一缓存槽，避免布局错乱。
索引对齐：通过 Span 协议（StaggeredGridItemSpan）计算每个子项占据的列数，并据此对齐相邻行的起始位置。跨度变化时，后续子项的行高会自动调整。
预布局与滚动稳定性：采用“快照布局”策略，滚动时先锁定已跨过的行索引，再按需填充新行。但若子项跨度频繁变化，会导致滚动抖动（Jank），因为需要重新计算行高。

  关键指标：复用命中率应 > 85%；滚动帧率稳定在 55 fps 以上，波动 < 5 ms。

4.2 实现流程与 API 使用

使用 LazyStaggeredGrid 搭建瀑布流通常分为三步：配置栅格规模、定义子项 span、填充数据。以下是一个典型实现：

@Composable
fun PhotoMasonry(photos: List<Photo>) {
    LazyStaggeredGrid(
        columns = StaggeredGridCells.Fixed(2),
        contentPadding = PaddingValues(8.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp),
        verticalItemSpacing = 8.dp,
        modifier = Modifier.fillMaxSize()
    ) {
        items(
            items = photos,
            key = { it.id }
        ) { photo ->
            // 根据图片宽高比动态计算 span
            val span = if (photo.aspectRatio > 1.5) 1 else 2
            StaggeredGridItemSpan(span)
        } item { photo ->
            PhotoCard(
                photo = photo,
                modifier = Modifier
                    .fillMaxWidth()
                    .heightIn(max = 300.dp)
            )
        }
    }
}

注意：StaggeredGridItemSpan 必须在 items 闭包之前定义，且每个子项只能声明一次 span。如果动态计算 span，务必配合 remember 保持值稳定。

4.3 参数对比：栅格列模式

模式	声明方式	适用场景	对齐稳定性
Fixed(n)	固定 n 列，每列等宽	已知最佳列数，内容宽度统一	高
Adaptive(minSize)	根据容器宽度自动计算列数，每列至少 minSize	响应式瀑布流	中（旋转时需重新计算）
Mixed（Fixed + Adaptive）	通过 `StaggeredGridCells.adaptive` 配合 `.fixed` 组合	部分列固定，其余自适应（不常用）	较低（需手动处理 span 冲突）

推荐在大多数瀑布流场景中使用 StaggeredGridCells.Fixed(2) 或 Fixed(3)，既能保证索引对齐简单，又能减少滚动重算。

4.4 核心结构：索引对齐与复用机制

下图展示了 LazyStaggeredGrid 在 2 列模式下，不同 span 子项如何对齐以及复用池如何组织：

图中 A（span=1）与 B（span=2）处于同一起始行；B 占用两列，因此下方行从 A 的底部开始。C 的 span=1 被放置在 B 左侧的空隙中，D 则从 C 底部另起一行。复用池根据 span 值（1 或 2）分别缓存已滚出屏幕的子项，避免重新创建。

4.5 调试：滚动抖动与索引漂移分析

滚动抖动通常由以下原因引起，可通过 Android Studio 的 Layout Inspector 和 GPU 渲染分析 排查：

跨度过频变化：每次 recomposition 都重新计算 span，导致布局高度不稳定。应使用 remember 缓存计算结果。
错误的 key 设置：未使用稳定唯一的 key，导致 Compose 无法正确识别子项复用，触发全量重组。
measurePolicy 被动触发的重算：当父容器尺寸变化或子项内部状态变化时，LazyStaggeredGrid 会重新测量所有可见项，造成帧率下降。

调试命令：在 Gradle 控制台执行 adb shell dumpsys gfxinfo <package> 查看帧时间。若 Jank 帧比例 > 5%，优先检查 span 变更频率。

4.6 常见错误与解决方案

错误现象	原因	解决办法
子项重叠或错位	`StaggeredGridItemSpan` 声明在 `item` 块外部，或 span 值与实际列数不匹配	确保 span 定义在 `items` 闭包内，且不超过列数（如2列时span最大为2）
滚动时布局抖动	子项高度由异步数据（如图片加载）动态改变，导致布局重新测量	使用固定占位高度，或通过 `Modifier.heightIn` 限制最大高度
复用池泄漏或内存增长	未设置 `key` 或 key 类型可变，导致 Compose 认为每个子项都是新插入	始终使用 `key = { it.id }`，且 id 为不变字符串或数字
首屏加载缓慢	子项数量过多，或 `contentPadding` 配置过大导致预布局浪费	使用 `contentPadding = PaddingValues(horizontal = 8.dp)` 代替 large padding；必要时启用 `LazyStaggeredGridState` 的预取策略

4.7 性能优化最佳实践

为了达到 60 fps 流畅滚动，在瀑布流中应遵循以下规则：

稳定 span 计算：将 span 结果存入全局可缓存对象（如 List<Int>），避免在可组合函数内实时计算。
使用 StaggeredGridCells.Fixed：避免 Adaptive 在旋转或横竖屏切换时引发的全面重新测量。
限制最大跨跨度：span 值尽量不超过列数的一半（如 3 列时 span 只用 1 或 2），减少极端高度差异导致的布局碎片化。
启用 animateItemPlacement：对需要平滑移动的 item 添加 Modifier.animateItem()，但注意动画仅在明确定位改变时触发，不影响复用。

使用 remember 保持重计算状态：

val spanCache = remember(photos) {
    photos.map { if (it.aspectRatio > 1.5) 1 else 2 }
}

性能警讯：如果每个 item 都包含复杂的动态高度（如 WebView 或富文本），建议手动测量固定高度后传入 span，否则 LazyStaggeredGrid 会因频繁测量而导致严重掉帧。

4.8 部署监测与持续优化

发布后可通过 Firebase Performance Monitoring 或自定义 Trace 检测 LazyStaggeredGrid 的滚动帧率。如果发现 90% 分位帧率低于 40 fps，应回查 span 稳定性与 reuse 命中率。推荐在测试阶段使用 ComposeMetrics 库（需配合 Gradle plugin）自动化分析重组次数。

最终检查清单：✅ span 已缓存 ✅ key 稳定 ✅ 列模式固定 ✅ 占位高度限制 ✅ 预取策略默认开启。