scrollTargetLayout

在 SwiftUI 中，scrollTargetLayout 是 iOS 17+ 引入的一个关键修饰符，用于控制 滚动视图（如 ScrollView）的滚动定位行为。它通常与 scrollPosition 修饰符配合使用，能精准控制滚动目标的位置（例如分页滚动、自动对齐到特定子视图等）。

核心作用 #

定义滚动目标
标记哪些子视图是滚动视图的“定位单元”，帮助系统理解如何计算滚动位置。
自动化对齐
结合 scrollPosition 自动将内容对齐到最近的子视图或自定义位置。
分页支持
简化分页滚动（Paging）的实现，无需手动计算偏移量。

使用方式 #

1. 基本语法 #

将 scrollTargetLayout 应用在滚动视图的 子视图容器（如 LazyVStack、HStack）上：

ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemView(item: item)
        }
    }
    .scrollTargetLayout() // 标记子视图为滚动目标
}

2. 结合 `scrollPosition` #

通过 scrollPosition 绑定当前滚动位置，自动对齐到目标视图：

struct ContentView: View {
    @State private var scrollPosition: Int? // 跟踪当前滚动位置的标识符（如 id）

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(items) { item in
                    ItemView(item: item)
                        .id(item.id) // 必须为子视图提供唯一标识符
                }
            }
            .scrollTargetLayout() // 标记子视图为滚动目标
        }
        .scrollPosition(id: $scrollPosition) // 绑定当前滚动位置
    }
}

3. 实现分页滚动 #

自动对齐到子视图边界，实现分页效果：

ScrollView(.horizontal) {
    LazyHStack {
        ForEach(0..<10) { index in
            PageView(number: index)
                .frame(width: 300, height: 200)
                .id(index) // 唯一标识符
        }
    }
    .scrollTargetLayout() // 标记为滚动目标
}
.scrollTargetBehavior(.viewAligned) // 按子视图边界对齐（分页效果）

使用场景 #

场景	描述
分页滚动	水平/垂直分页，每次滚动一个完整子视图（如轮播图）
精准定位	根据业务逻辑自动滚动到指定子视图（如选中项居中）
动态布局对齐	滚动结束后自动对齐到最近的子视图边缘，提升交互流畅性

代码示例：分页轮播图 #

struct CarouselView: View {
    let colors: [Color] = [.red, .green, .blue, .yellow, .purple]
    @State private var currentPage: Int = 0

    var body: some View {
        VStack {
            ScrollView(.horizontal) {
                LazyHStack(spacing: 0) {
                    ForEach(Array(colors.enumerated()), id: \.offset) { index, color in
                        color
                            .frame(width: 300, height: 200)
                            .overlay(Text("Page \(index + 1)"))
                            .id(index) // 唯一标识符
                    }
                }
                .scrollTargetLayout() // 标记为滚动目标
            }
            .scrollTargetBehavior(.viewAligned) // 按子视图对齐（分页）
            .scrollIndicators(.hidden)
            
            Text("当前页: \(currentPage + 1)")
        }
        .safeAreaPadding(.horizontal, 20) // 添加边距
    }
}

注意事项 #

标识符必填
子视图必须通过 .id() 提供唯一标识符，否则 scrollPosition 无法正确绑定。
性能优化
对于大量数据，优先使用 LazyVStack 或 LazyHStack 延迟加载子视图。
动态更新
如果数据源动态变化（如插入/删除项），需确保 scrollPosition 的标识符同步更新。
兼容性限制
仅支持 iOS 17+、macOS 14+ 等新系统版本。

总结 #

通过 scrollTargetLayout 和 scrollPosition 的组合，SwiftUI 提供了一种声明式的滚动定位方案，能轻松实现分页、自动对齐等高级交互效果。相比手动计算偏移量，这种方式更简洁且不易出错，适合需要精准控制滚动行为的场景。