Jetpack Compose实现CollapsingToolbar滚动复位异常修复

数据老陈

2026-8-27

问题产生原因

核心问题出在NestedScrollConnection的滚动消费逻辑实现错误，和动态高度计算本身无关，动态高度变化只是放大了错位的表现：

目前onPreScroll方法无论实际消费了多少滚动距离，都固定返回Offset.Zero，等于告诉Compose嵌套滚动体系「当前父布局没有消费任何滚动事件」，但实际上你已经修改了toolbarOffsetHeightPx的值，占用了部分/全部滚动偏移量。
这种「实际消费了滚动但不告知系统」的行为，会导致滚动量计算错位：系统会把所有滚动偏移都派发给内部的可滚动内容（DetailsContent里的列表/滚动容器），当滚动容器已经滑到顶部无法继续下滑时，本该用来展开工具栏的剩余滚动量会被丢失，最终toolbarOffsetHeightPx就会残留负值，无法回到0的完全展开状态。
现有逻辑没有区分滚动优先级：下滑时没有判断内部滚动容器是否已经回到顶部，就提前抢占滚动量修改工具栏偏移，进一步加剧了偏移量计算的不同步，加上动态修改内容高度会触发重组改变可滚动容器的布局边界，最终表现为工具栏展开状态不稳定。

修复方案

按以下步骤调整即可，原有动态计算boxHeight、imageHeight的逻辑不需要改动：

修正滚动偏移返回值：在onPreScroll中准确计算实际消费的y轴滚动距离，返回给嵌套滚动系统，不要固定返回Offset.Zero
明确滚动优先级：
- 上滑（手指向上移动，y轴delta为负）时，优先消费滚动量折叠工具栏，直到工具栏完全折叠后，剩余滚动量再交给内部内容滚动
- 下滑（手指向下移动，y轴delta为正）时，先判断内部可滚动内容是否已经回到顶部，只有内容到顶后，才消费滚动量展开工具栏
补充fling（快速滑动）场景的偏移修正，避免快速滑动时出现偏移残留

修复后的NestedScrollConnection实现代码如下：

val toolbarHeightPx = with(LocalDensity.current) {
    278.dp.roundToPx().toFloat()
}
val toolbarOffsetHeightPx = remember { mutableStateOf(0f) }
// 这里需要引用你DetailsContent对应的滚动状态，普通ScrollState/LazyListState都适配
val nestedScrollConnection = remember(scrollState) {
    object : NestedScrollConnection {
        override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
            val deltaY = available.y
            var consumedY = 0f

            // 上滑场景：优先折叠工具栏
            if (deltaY < 0) {
                val targetOffset = (toolbarOffsetHeightPx.value + deltaY).coerceIn(-toolbarHeightPx, 0f)
                consumedY = targetOffset - toolbarOffsetHeightPx.value
                toolbarOffsetHeightPx.value = targetOffset
            }
            // 下滑场景：仅当内部内容滚动到顶部时才展开工具栏
            else if (deltaY > 0) {
                // canScrollBackward为false代表内容已经在最顶部，无法继续向下滚动
                val contentReachTop = !scrollState.canScrollBackward
                if (contentReachTop) {
                    val targetOffset = (toolbarOffsetHeightPx.value + deltaY).coerceIn(-toolbarHeightPx, 0f)
                    consumedY = targetOffset - toolbarOffsetHeightPx.value
                    toolbarOffsetHeightPx.value = targetOffset
                }
            }

            // 只返回y轴实际消费的偏移，x轴不做处理返回0
            return Offset(0f, consumedY)
        }

        override fun onPostFling(consumed: Velocity, available: Velocity): Velocity {
            val availableY = available.y
            var consumedY = 0f

            // 下滑fling时内容到顶，直接将工具栏展开到完整状态
            if (availableY > 0 && !scrollState.canScrollBackward) {
                toolbarOffsetHeightPx.value = 0f
                consumedY = availableY
            }
            // 上滑fling时工具栏未完全折叠，直接折叠到收起状态
            else if (availableY < 0 && toolbarOffsetHeightPx.value > -toolbarHeightPx) {
                toolbarOffsetHeightPx.value = -toolbarHeightPx
                consumedY = availableY
            }

            return Velocity(0f, consumedY)
        }
    }
}

如果需要更顺滑的展开/折叠动画，可以把fling里直接赋值offset的逻辑替换为animateTo的动画实现，基础场景下上面的代码已经可以解决偏移残留、无法完全展开的问题。

内容的提问来源于stack exchange，提问作者Ali