Swift中UICollectionView调用scrollToItem跳转时cell异常上移问题

触发原因 #

• 调用scrollToItem时使用的.centeredHorizontally对齐方式不符合水平分页场景的对齐逻辑，触发了不必要的垂直偏移计算
• UICollectionViewController默认的滚动内边距自动调整逻辑会干扰滚动位置的计算

修复步骤 #

1. 替换nextButtonOnClicked中的滚动逻辑，直接手动设置contentOffset，和手势滑动的计算逻辑保持完全一致，稳定性更高

func nextButtonOnClicked() {
    guard pageControl.currentPage < 2 else { return }
    let nextIndex = pageControl.currentPage + 1
    pageControl.currentPage = nextIndex
    // 直接按分页规则计算偏移，避免scrollToItem的布局异常
    let targetOffset = CGPoint(x: CGFloat(nextIndex) * view.frame.width, y: 0)
    collectionView?.setContentOffset(targetOffset, animated: false)
}

2. 在viewDidLoad中新增配置，禁用系统自动调整滚动内边距

override func viewDidLoad() {
    super.viewDidLoad()
    // 新增以下两行配置
    automaticallyAdjustsScrollViewInsets = false
    collectionView.contentInsetAdjustmentBehavior = .never

    // 原有逻辑保持不变
    self.title = "Test"
    collectionView.backgroundColor = .white
    collectionView.register(UserQuickGuideCell.self, forCellWithReuseIdentifier: "cellId")
    collectionView.isPagingEnabled = true
    
    setupPageControl()
}

可选优化 #

如果需要保留scrollToItem的调用方式，需要做两处调整：

• 明确设置collectionView布局的滚动方向为水平

if let layout = collectionViewLayout as? UICollectionViewFlowLayout {
    layout.scrollDirection = .horizontal
}

• 将scrollToItem的对齐方式改为.left，和分页场景的对齐逻辑匹配

collectionView?.scrollToItem(at: indexPath, at: .left, animated: false)

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