如何实现RecyclerView+PagerSnapHelper的平滑循环20%预览效果？

需求概述 #

使用水平RecyclerView + PagerSnapHelper模拟ViewPager，子视图已占满RecyclerView宽度，需实现：

• 显示下一条目约20%的预览，提示用户可水平滑动
• 滑动结束后，当前条目自动对齐归位
• 支持循环滚动（最后一条的预览为第一条）

当前实现的问题 #

直接使用scrollToPositionWithOffset存在以下问题：

• 滚动动画不流畅
• PagerSnapHelper的自动对齐功能失效
• 循环预览逻辑不完善

简洁解决方案 #

核心思路是自定义PagerSnapHelper控制对齐位置，配合循环Adapter实现需求，无需调整子视图宽度。

1. 自定义PeekingPagerSnapHelper #

重写SnapHelper核心方法，让当前条目左对齐，下一条目固定露出20%宽度：

class PeekingPagerSnapHelper(private val peekWidthRatio: Float = 0.2f) : PagerSnapHelper() {
    private var layoutManager: LinearLayoutManager? = null

    override fun attachToRecyclerView(recyclerView: RecyclerView?) {
        super.attachToRecyclerView(recyclerView)
        layoutManager = recyclerView?.layoutManager as? LinearLayoutManager
    }

    override fun calculateDistanceToFinalSnap(layoutManager: RecyclerView.LayoutManager, targetView: View): IntArray? {
        val out = IntArray(2)
        if (layoutManager.canScrollHorizontally()) {
            val recyclerViewWidth = layoutManager.width
            val peekWidth = (recyclerViewWidth * peekWidthRatio).toInt()
            // 计算偏移量，让下一条目露出指定宽度
            out[0] = targetView.left - peekWidth
        } else {
            out[0] = 0
        }
        out[1] = 0
        return out
    }

    override fun findSnapView(layoutManager: RecyclerView.LayoutManager): View? {
        val linearLayoutManager = layoutManager as LinearLayoutManager
        val firstVisiblePos = linearLayoutManager.findFirstVisibleItemPosition()
        val realItemCount = layoutManager.adapter?.itemCount?.takeIf { it > 0 } ?: return null

        // 修正循环位置到真实数据范围
        val nextPos = firstVisiblePos + 1
        val currentView = linearLayoutManager.findViewByPosition(firstVisiblePos)
        val nextView = linearLayoutManager.findViewByPosition(nextPos)

        return if (nextView != null && nextView.left < layoutManager.width) {
            // 下一条目已露出，对齐当前条目保持预览效果
            currentView
        } else {
            super.findSnapView(layoutManager)
        }
    }
}

2. 实现循环Adapter #

通过设置极大itemCount并对位置取模，实现无限循环滚动：

class CarouselAdapter(private val items: List<YourDataModel>) : RecyclerView.Adapter<CarouselViewHolder>() {
    private val realItemCount = items.size

    // 用极大值模拟无限循环
    override fun getItemCount(): Int = if (realItemCount == 0) 0 else Integer.MAX_VALUE

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): CarouselViewHolder {
        val view = LayoutInflater.from(parent.context)
            .inflate(R.layout.item_carousel, parent, false)
        // 强制子视图宽度等于RecyclerView宽度
        view.layoutParams.width = parent.width
        return CarouselViewHolder(view)
    }

    override fun onBindViewHolder(holder: CarouselViewHolder, position: Int) {
        // 取模得到真实数据位置
        val realPosition = position % realItemCount
        holder.bind(items[realPosition])
    }
}

3. 初始化RecyclerView #

将自定义SnapHelper和循环Adapter绑定到RecyclerView：

// 初始化RecyclerView
val carouselRv = findViewById<RecyclerView>(R.id.carousel_recycler_view)
val layoutManager = LinearLayoutManager(this, LinearLayoutManager.HORIZONTAL, false)
carouselRv.apply {
    this.layoutManager = layoutManager
    adapter = CarouselAdapter(yourDataList)
    setHasFixedSize(true)
    // 绑定自定义SnapHelper，设置20%预览比例
    PeekingPagerSnapHelper(0.2f).attachToRecyclerView(this)
}

// 平滑滚动到下一个预览位置的方法
fun scrollToNextPreview() {
    val currentPos = layoutManager.findFirstVisibleItemPosition()
    carouselRv.smoothScrollToPosition(currentPos + 1)
}

效果说明 #

• 滚动流畅：使用RecyclerView原生smoothScrollToPosition实现平滑动画
• Snap功能正常：自定义SnapHelper确保滚动结束后自动对齐到预览位置
• 循环支持：Adapter取模逻辑和SnapHelper位置修正实现无缝循环

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