如何为CollectionView顶部添加固定常驻的淡出渐变效果

需求说明 #

需要为UICollectionView添加类似Instagram直播列表的顶部固定淡出效果，效果不会随列表滚动发生位移。

原有实现的问题 #

之前尝试使用CAGradientLayer实现未达预期，原有代码如下：

private func setFadeOut() {
let collectionViewGradient = CAGradientLayer()
collectionViewGradient.colors = [
    UIColor.gray.withAlphaComponent(0.2).cgColor,
    UIColor.gray.withAlphaComponent(0.1).cgColor,
    UIColor.clear.cgColor
]
collectionViewGradient.frame = view.bounds
collectionViewGradient.startPoint = CGPoint(x: 0, y: 0)
collectionViewGradient.endPoint = CGPoint(x: 0, y: 1)
collectionView.layer.insertSublayer(collectionViewGradient, at: 0)
}

原有代码的核心问题：

• 直接添加半透明灰色子图层，而非通过图层mask实现内容透明度过渡，最终会显示一层发灰的蒙层，不是内容自然淡出的效果
• 渐变范围覆盖整个CollectionView高度，而非仅顶部一小段淡出区域
• 渐变图层被插入到图层树最底层，会被滚动的Cell完全遮挡
• 没有在布局更新时同步渐变层frame，页面尺寸变化时渐变位置会错位

正确实现代码 #

实现逻辑是将CAGradientLayer设置为CollectionView的layer mask，通过alpha通道控制内容的显示透明度，仅在顶部指定高度范围内做透明渐变，其余区域保持内容完全可见，同时在布局回调里同步渐变层尺寸，保证渐变始终固定在视图顶部。

// 顶部淡出渐变层
private let topFadeMask = CAGradientLayer()
// 顶部淡出高度，可根据设计需求调整
private let fadeHeight: CGFloat = 30

private func setupTopFadeEffect() {
    // 渐变方向为垂直从上到下
    topFadeMask.startPoint = CGPoint(x: 0.5, y: 0)
    topFadeMask.endPoint = CGPoint(x: 0.5, y: 1)
    // mask通过alpha控制显隐：透明位置内容隐藏，不透明位置内容正常显示
    topFadeMask.colors = [
        UIColor.clear.cgColor,
        UIColor.white.cgColor
    ]
    collectionView.layer.mask = topFadeMask
}

override func viewDidLayoutSubviews() {
    super.viewDidLayoutSubviews()
    guard collectionView.bounds.height > 0 else { return }
    // 按视图总高度计算渐变位置占比，保证渐变仅出现在顶部fadeHeight区域
    let fadeRatio = NSNumber(value: Float(fadeHeight / collectionView.bounds.height))
    topFadeMask.locations = [0, fadeRatio]
    // 渐变层尺寸匹配整个CollectionView，保证滚动时渐变位置固定
    topFadeMask.frame = collectionView.bounds
}

在viewDidLoad中调用setupTopFadeEffect()即可生效。如果需要调整淡出的柔和度，可以在colors数组中添加中间透明度的颜色，同步在locations中设置对应位置比例即可。

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