使用ScrollView+LazyHStack的SwiftUI轮播文本截断问题求助

开发者阿泽

2026-6-24

问题

使用SwiftUI的LazyHStack和ScrollView实现轮播视图时，当轮播项内容高度不一致，会出现内容被裁剪的情况。原因是LazyHStack默认以第一个元素的高度为基准分配空间，改用HStack虽能解决但会失去懒加载的性能优势。

尝试过隐藏占位视图方案：通过ZStack包含所有轮播项的文本内容作为占位来预留最高元素的空间，再叠加实际内容，但偶尔仍会出现文本截断，且截断情况随内容、图片尺寸随机出现。

实现代码

CarouselView 实现

struct CarouselView<Content: View>: View {
    let content: Content
    @State private var currentIndex = 0
    @State private var contentSize: CGSize = .zero
    
    private let showsIndicators: Bool
    private let spacing: CGFloat
    private let shouldSnap: Bool
    
    init(showsIndicators: Bool = true,
         spacing: CGFloat = .zero,
         shouldSnap: Bool = false,
         @ViewBuilder content: @escaping () -> Content) {
        self.content = content()
        self.showsIndicators = showsIndicators
        self.spacing = spacing
        self.shouldSnap = shouldSnap
    }
    
    var body: some View {
        VStack {
            ScrollView(.horizontal, showsIndicators: showsIndicators) {
                LazyHStack(spacing: spacing) {
                    content
                }.apply {
                    if #available(iOS 17.0, *), shouldSnap {
                        $0.scrollTargetLayout()
                    } else {
                        $0
                    }
                }
            }
            .clipped() // tried to add this to avoid clipping
            .apply {
                if #available(iOS 17.0, *), shouldSnap {
                    $0.scrollTargetBehavior(.viewAligned)
                } else {
                    $0
                }
            }
        }
    }
}

extension View {
    func apply<V: View>(@ViewBuilder _ block: (Self) -> V) -> V { block(self) }
}

DemoTileView 实现

struct DemoTileView: View {
    
    private let imageName: String
    private let imageWidth: CGFloat
    private let imageHeight: CGFloat
    private let title: String
    private let supportingText: String
    private let allTitles: [String]
    private let allSupportingText: [String]
    
    init(imageName: String,
         title: String,
         allTitles: [String],
         supportingText: String,
         allSupportingText: [String],
         imageWidth: CGFloat,
         imageHeight: CGFloat) {
        self.imageName = imageName
        self.title = title
        self.supportingText = supportingText
        self.allTitles = allTitles
        self.allSupportingText = allSupportingText
        self.imageWidth = imageWidth
        self.imageHeight = imageHeight
    }
    
    var body: some View {
        VStack(spacing: .zero) {
            Image(imageName)
                .resizable()
                .scaledToFill()
                .frame(width: imageWidth, height: imageHeight)
                .clipShape(RoundedRectangle(cornerRadius: Constants.Border.cornerRadius))
                .padding(.bottom, Constants.Padding.imageBottom)
            
            textViewFootprint
                .overlay(alignment: .top) {
                    createTextView(title: title, supportingText: supportingText)
                }
            
            Spacer() // added to top align content
        }
        .frame(width: imageWidth)
    }
    
    // This the footprint / placeholder view used to reserve the height needed
    private var textViewFootprint: some View {
        ZStack {
            ForEach(allTitles.indices, id: \.self) { index in
                let currentTitle = allTitles[index]
                let currentSupportingText = allSupportingText[index]
                createTextView(title: currentTitle, supportingText: currentSupportingText)
            }
        }
        .hidden()
    }
    
    private func createTextView(title: String, supportingText: String) -> some View {
        VStack {
            createTitleView(for: title)
            createSupportingTextView(for: title)
        }
    }
    
    private func createTitleView(for text: String) -> some View {
        // In an HStack to left align the text
        HStack {
            Text(text)
                .bold()
                .padding(.bottom, Constants.Padding.titleBottom)
            
            Spacer()
        }
    }
    
    private func createSupportingTextView(for text: String) -> some View {
        // In an HStack to left align the text
        HStack {
            Text(supportingText)
                .padding(.bottom, Constants.Padding.supportingTextBottom)
            
            Spacer()
        }
    }
    
    struct Constants {
        struct Padding {
            static let imageBottom = 12.0
            static let titleBottom = 4.0
            static let supportingTextBottom = 20.0
        }
        
        struct Border {
            static let cornerRadius = 30.0
        }
    }
}

调用代码

CarouselView(spacing: 10) {
    ForEach(0 ..< imagesNames.count, id: \.self) { index in
        DemoTileView(imageName: imagesNames[index],
                     title: titles[index],
                     allTitles: titles,
                     supportingText: supportingText[index],
                     allSupportingText: supportingText,
                     imageWidth: 180,
                     imageHeight: 120)
        .onTapGesture {
            defaultCarouselIndexTapped = index
        }
    }
}

解决方案

优化现有占位视图方案

针对当前方案的文本截断问题，从以下几点修正：

修复占位视图文本参数错误
当前createSupportingTextView方法存在参数误用，导致占位视图文本与实际内容不一致，这是截断的核心原因之一。修正代码：

private func createSupportingTextView(for text: String) -> some View {
    HStack {
        Text(text) // 改为使用传入的参数text，而非外部变量
            .padding(.bottom, Constants.Padding.supportingTextBottom)
        
        Spacer()
    }
}

给占位视图添加固定宽度约束
给占位视图明确设置与轮播项一致的宽度，避免布局计算偏差：

private var textViewFootprint: some View {
    ZStack {
        ForEach(allTitles.indices, id: \.self) { index in
            createTextView(title: allTitles[index], supportingText: allSupportingText[index])
        }
    }
    .frame(width: imageWidth) // 新增固定宽度
    .hidden()
}

简化布局，明确对齐方式
移除多余的Spacer，通过VStack的alignment参数控制左对齐，避免布局混乱：

var body: some View {
    VStack(alignment: .leading, spacing: Constants.Padding.imageBottom) {
        Image(imageName)
            .resizable()
            .scaledToFill()
            .frame(width: imageWidth, height: imageHeight)
            .clipShape(RoundedRectangle(cornerRadius: Constants.Border.cornerRadius))
        
        textViewFootprint
            .overlay(alignment: .topLeading) { // 匹配文本左对齐
                createTextView(title: title, supportingText: supportingText)
            }
    }
    .frame(width: imageWidth)
}

同时简化文本布局，无需嵌套HStack：

private func createTextView(title: String, supportingText: String) -> some View {
    VStack(alignment: .leading, spacing: Constants.Padding.titleBottom) {
        Text(title)
            .bold()
        Text(supportingText)
            .padding(.bottom, Constants.Padding.supportingTextBottom)
    }
}

替代方案：动态计算最大高度

如果占位视图方案仍不稳定，可以通过GeometryReader提前计算所有轮播项的最大高度，给LazyHStack设置固定高度：

修改后的CarouselView

struct CarouselView<Content: View>: View {
    let content: Content
    let itemsCount: Int
    @State private var currentIndex = 0
    @State private var maxItemHeight: CGFloat = 0
    
    private let showsIndicators: Bool
    private let spacing: CGFloat
    private let shouldSnap: Bool
    
    init(itemsCount: Int,
         showsIndicators: Bool = true,
         spacing: CGFloat = .zero,
         shouldSnap: Bool = false,
         @ViewBuilder content: @escaping () -> Content) {
        self.itemsCount = itemsCount
        self.content = content()
        self.showsIndicators = showsIndicators
        self.spacing = spacing
        self.shouldSnap = shouldSnap
    }
    
    var body: some View {
        VStack {
            ScrollView(.horizontal, showsIndicators: showsIndicators) {
                LazyHStack(spacing: spacing) {
                    content
                        .background(
                            GeometryReader { proxy in
                                Color.clear
                                    .preference(key: ItemHeightKey.self, value: proxy.size.height)
                            }
                        )
                }
                .frame(height: maxItemHeight) // 设置固定高度
                .apply {
                    if #available(iOS 17.0, *), shouldSnap {
                        $0.scrollTargetLayout()
                    } else {
                        $0
                    }
                }
            }
            .onPreferenceChange(ItemHeightKey.self) { heights in
                maxItemHeight = heights.max() ?? 0
            }
            .apply {
                if #available(iOS 17.0, *), shouldSnap {
                    $0.scrollTargetBehavior(.viewAligned)
                } else {
                    $0
                }
            }
        }
    }
}

struct ItemHeightKey: PreferenceKey {
    static var defaultValue: [CGFloat] = []
    static func reduce(value: inout [CGFloat], nextValue: () -> [CGFloat]) {
        value.append(contentsOf: nextValue())
    }
}

调用方式（简化DemoTileView）

移除DemoTileView中的占位视图相关代码，调用时传入轮播项数量：

CarouselView(itemsCount: imagesNames.count, spacing: 10) {
    ForEach(0 ..< imagesNames.count, id: \.self) { index in
        DemoTileView(imageName: imagesNames[index],
                     title: titles[index],
                     supportingText: supportingText[index],
                     imageWidth: 180,
                     imageHeight: 120)
        .onTapGesture {
            defaultCarouselIndexTapped = index
        }
    }
}

方案对比

优化后的占位视图方案：无需额外状态管理，保持懒加载优势，适合内容固定且提前已知的场景。
动态高度计算方案：更灵活，支持动态内容，但首次加载时会有短暂的布局计算过程。

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

使用ScrollView+LazyHStack的SwiftUI轮播文本截断问题求助

问题 #

实现代码 #