SwiftUI 容器参考
栈、网格、大纲和滚动增强。iOS 14 至 iOS 26。
来源:WWDC 2020-10031、2022-10056、2023-10148、2024-10144、2025-256
快速决策
| 使用场景 | 容器 | iOS |
|---|---|---|
| 固定视图垂直/水平 | VStack / HStack | 13+ |
| 重叠视图 | ZStack | 13+ |
| 大型可滚动列表 | LazyVStack / LazyHStack | 14+ |
| 多列网格 | LazyVGrid | 14+ |
| 多行网格(水平) | LazyHGrid | 14+ |
| 静态网格,精确对齐 | Grid | 16+ |
| 分层数据(树) | List 使用 children: | 14+ |
| 自定义层级 | OutlineGroup | 14+ |
| 显示/隐藏内容 | DisclosureGroup | 14+ |
第一部分:栈
VStack、HStack、ZStack
VStack(alignment: .leading, spacing: 12) {
Text("标题")
Text("副标题")
}
HStack(alignment: .top, spacing: 8) {
Image(systemName: "star")
Text("评分")
}
ZStack(alignment: .bottomTrailing) {
Image("photo")
Badge()
}
ZStack 对齐方式:.center(默认)、.top、.bottom、.leading、.trailing、.topLeading、.topTrailing、.bottomLeading、.bottomTrailing
Spacer
HStack {
Text("左侧")
Spacer()
Text("右侧")
}
Spacer(minLength: 20) // 最小尺寸
LazyVStack、LazyHStack(iOS 14+)
仅在视图可见时渲染子视图。请配合 ScrollView 使用。
ScrollView {
LazyVStack(spacing: 0) {
ForEach(items) { item in
ItemRow(item: item)
}
}
}
固定的分区标题
ScrollView {
LazyVStack(pinnedViews: [.sectionHeaders]) {
ForEach(sections) { section in
Section(header: SectionHeader(section)) {
ForEach(section.items) { item in
ItemRow(item: item)
}
}
}
}
}
第二部分:网格
Grid(iOS 16+)
非惰性网格,支持精确对齐。一次性加载所有视图。
Grid(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10) {
GridRow {
Text("姓名")
TextField("输入姓名", text: $name)
}
GridRow {
Text("邮箱")
TextField("输入邮箱", text: $email)
}
}
修饰符:
gridCellColumns(_:)— 跨越多个列gridColumnAlignment(_:)— 覆盖列对齐
Grid {
GridRow {
Text("表头").gridCellColumns(2)
}
GridRow {
Text("左侧")
Text("右侧").gridColumnAlignment(.trailing)
}
}
LazyVGrid(iOS 14+)
垂直滚动网格。定义列;行数无限制增长。
let columns = [
GridItem(.flexible()),
GridItem(.flexible()),
GridItem(.flexible())
]
ScrollView {
LazyVGrid(columns: columns, spacing: 16) {
ForEach(items) { item in
ItemCard(item: item)
}
}
}
LazyHGrid(iOS 14+)
水平滚动网格。定义行;列数无限制增长。
let rows = [GridItem(.fixed(100)), GridItem(.fixed(100))]
ScrollView(.horizontal) {
LazyHGrid(rows: rows, spacing: 16) {
ForEach(items) { item in
ItemCard(item: item)
}
}
}
GridItem.Size
| 尺寸 | 行为 |
|---|---|
.fixed(CGFloat) | 精确的宽度/高度 |
.flexible(minimum:maximum:) | 均匀填充空间 |
.adaptive(minimum:maximum:) | 创建尽量多的项目 |
// 自适应:列数响应式
let columns = [GridItem(.adaptive(minimum: 150))]
第三部分:大纲
带分层数据的 List(iOS 14+)
struct FileItem: Identifiable {
let id = UUID()
var name: String
var children: [FileItem]? // nil 表示叶子节点
}
List(files, children: \.children) { file in
Label(file.name, systemImage: file.children != nil ? "文件夹" : "文档")
}
.listStyle(.sidebar)
OutlineGroup(iOS 14+)
用于在 List 外部实现自定义层级布局。
List {
ForEach(canvases) { canvas in
Section(header: Text(canvas.name)) {
OutlineGroup(canvas.graphics, children: \.children) { graphic in
GraphicRow(graphic: graphic)
}
}
}
}
DisclosureGroup(iOS 14+)
@State private var isExpanded = false
DisclosureGroup("高级选项", isExpanded: $isExpanded) {
Toggle("启用功能", isOn: $feature)
Slider(value: $intensity)
}
第四部分:常见模式
照片网格
let columns = [GridItem(.adaptive(minimum: 100), spacing: 2)]
ScrollView {
LazyVGrid(columns: columns, spacing: 2) {
ForEach(photos) { photo in
AsyncImage(url: photo.thumbnailURL) { image in
image.resizable().aspectRatio(1, contentMode: .fill)
} placeholder: { Color.gray }
.aspectRatio(1, contentMode: .fill)
.clipped()
}
}
}
水平轮播
ScrollView(.horizontal, showsIndicators: false) {
LazyHStack(spacing: 16) {
ForEach(items) { item in
CarouselCard(item: item).frame(width: 280)
}
}
.padding(.horizontal)
}
文件浏览器
List(selection: $selection) {
OutlineGroup(rootItems, children: \.children) { item in
Label {
Text(item.name)
} icon: {
Image(systemName: item.children != nil ? "folder.fill" : "doc.fill")
}
}
}
.listStyle(.sidebar)
第五部分:性能
何时使用惰性
| 尺寸 | 可滚动? | 使用 |
|---|---|---|
| 1-20 | 否 | VStack/HStack |
| 1-20 | 是 | 在 ScrollView 中使用 VStack/HStack |
| 20-100 | 是 | LazyVStack/LazyHStack |
| 100+ | 是 | LazyVStack/LazyHStack 或 List |
| 网格 <50 | 否 | Grid |
| 网格 50+ | 是 | LazyVGrid/LazyHGrid |
缓存 GridItem 数组 — 在 body 外部定义:
struct ContentView: View {
let columns = [GridItem(.adaptive(minimum: 150))] // ✅
var body: some View {
LazyVGrid(columns: columns) { ... }
}
}
iOS 26 性能
- 列表加载速度提升 6 倍(针对 10 万+ 项目)
- 列表更新速度提升 16 倍
- 滚动时丢帧减少
- 嵌套 ScrollView 与惰性栈现在能正确延迟加载:
ScrollView(.horizontal) {
LazyHStack {
ForEach(photoSets) { set in
ScrollView(.vertical) {
LazyVStack {
ForEach(set.photos) { PhotoView(photo: $0) }
}
}
}
}
}
第六部分:滚动增强
containerRelativeFrame(iOS 17+)
根据滚动容器调整视图尺寸。
ScrollView(.horizontal) {
LazyHStack {
ForEach(cards) { card in
CardView(card: card)
.containerRelativeFrame(.horizontal, count: 3, span: 1, spacing: 16)
}
}
}
scrollTargetLayout(iOS 17+)
启用吸附效果。
ScrollView(.horizontal) {
LazyHStack {
ForEach(items) { ItemCard(item: $0) }
}
.scrollTargetLayout()
}
.scrollTargetBehavior(.viewAligned)
scrollPosition(iOS 17+)
跟踪最顶端可见项目。每个项目都需要 .id()。
@State private var position: Item.ID?
ScrollView {
LazyVStack {
ForEach(items) { item in
ItemRow(item: item).id(item.id)
}
}
}
.scrollPosition(id: $position)
scrollTransition(iOS 17+)
.scrollTransition { content, phase in
content
.opacity(1 - abs(phase.value) * 0.5)
.scaleEffect(phase.isIdentity ? 1.0 : 0.75)
}
onScrollGeometryChange(iOS 18+)
.onScrollGeometryChange(for: Bool.self) { geo in
geo.contentOffset.y < geo.contentInsets.top
} action: { _, isTop in
showBackButton = !isTop
}
onScrollVisibilityChange(iOS 18+)
VideoPlayer(player: player)
.onScrollVisibilityChange(threshold: 0.2) { visible in
visible ? player.play() : player.pause()
}
资源
WWDC:2020-10031、2022-10056、2023-10148、2024-10144、2025-256
文档:/swiftui/lazyvstack、/swiftui/lazyvgrid、/swiftui/lazyhgrid、/swiftui/grid、/swiftui/outlinegroup、/swiftui/disclosuregroup
技能:axiom-swiftui-layout、axiom-swiftui-layout-ref、axiom-swiftui-nav、axiom-swiftui-26-ref