SwiftUI Form 实战：从设置页到动态表单的完整指南与避坑经验

做 iOS 客户端这几年，我发现自己写的页面里，SwiftUI 的 Form 出现频率是真的高。设置页、个人资料编辑、筛选条件、审批录入……凡是那种"一行一行收集信息"的界面，Form 基本都是首选。它给我的感觉就像一个自带精装修的毛坯房，你只需要把家具摆进去，系统会帮你把墙体、地板、圆角、分隔线全部处理妥当。这篇文章不聊官网上那些 Hello World，就聊我把 Form 用进生产项目后的实战经验：它免费赠送的能力有哪些、常用控件怎么组合、动态数据怎么绑，以及几个文档里根本没写、但不踩不行的坑。

1. 为什么建议直接上 Form，而不是手搓 ScrollView + VStack

先讲一段我自己交过学费的经历。早期写一个账号设置页，我习惯用 ScrollView 包 VStack，再手动给每行加背景色、加圆角、控制分隔线。前两版需求简单，改起来也算顺手。直到某次版本迭代，产品要求在设置项超过一屏时，底部悬浮一个"保存修改"按钮。手搓方案当场崩溃：ScrollView 内容高度撑开之后，safe area 要自己算、键盘弹起时内容被顶掉的 inset 要自己处理、分隔线与分组圆角的间距在不同机型上还对不齐。那版改完我彻底弃坑，所有类似页面全部换成 Form。

Form 免费送你的东西，比大部分人想象中多：

• 自动分组视觉。Section 天然带毛玻璃质感的圆角卡片背景，多个分组之间自动留白，不需要你手动画圆角矩形。
• 系统级 insetGrouped 样式。在 iOS 上它默认采用列表的 insetGrouped 外观，跟系统设置 App 观感一致，用户看着就眼熟。
• 键盘与滚动联动。当键盘弹起时，Form 所在的滚动区域会自动调整 inset，当前聚焦的输入框基本不会被挡住，这个手搓 ScrollView 至少要多写十几行代码。
• 静态内容自动撑开。不需要手动设置 VStack 的宽高，Form 自己是滚动容器，内容多时自动滚，内容少时也不会出现空白跳动。

不过 Form 也不是万能钥匙。我目前的判断标准是：如果页面是"结构化地收集少量信息，且希望系统统一外观"，直接 Form；如果页面是"复杂卡片式信息流、瀑布流、需要高度自定义 cell 布局"，那就用 LazyVGrid 或 List 自绘行；如果表单项超过一两百个（比如超长配置项集合），Form 的静态视图树渲染成本会偏高，很长列表还是 List + LazyVStack 兜底更稳。日常业务场景里，一个设置页、资料页基本在 10 到 30 行之间，Form 的性能完全不需要担心。

还有一个容易被忽略的优势：Form 对辅助功能（VoiceOver）的支持是系统级的。手搓列表时，每行的 accessibility 元素顺序、是否合并成单个元素、焦点朗读顺序都要手动维护，而 Form 会根据 Section 结构自动组织朗读顺序。这一点在接无障碍需求时能省不少事。

2. Form 内建控件的组合套路：从设置页到复杂录入

Form 的骨架是 Section。我的习惯是：一个 Section 只放一类事情。比如通知设置页，我会把"消息通知总开关"放在第一个 Section，"具体哪些事件推送"放第二个 Section，"推送时是否显示详情"放第三个 Section。这样分组的视觉锚点非常清楚，用户扫一眼就能理解层级。

给一个偏完整的示例，这是一个"消息通知设置"页的核心结构：

swift复制Form {
    Section {
        Toggle("接收推送通知", isOn: $pushEnabled)
    } header: {
        Text("总开关")
    } footer: {
        Text("关闭后不再接收任何推送消息")
    }

    if pushEnabled {
        Section {
            Toggle("评论提醒", isOn: $commentNotify)
            Toggle("点赞提醒", isOn: $likeNotify)
            Toggle("私信提醒", isOn: $messageNotify)
        } header: {
            Text("事件类型")
        }
    }

    Section {
        Picker("提醒时段", selection: $period) {
            Text("全天").tag(0)
            Text("仅白天").tag(1)
            Text("仅夜间").tag(2)
        }
        .pickerStyle(.menu)
    } header: {
        Text("推送时段")
    }

    Section {
        Stepper("保留天数: \(keepDays) 天", value: $keepDays, in: 1...90)
    } footer: {
        Text("超过该天数的推送记录将被自动清理")
    }
}

这里面有几个值得说明的细节。

Toggle 直接绑定 Bool 即可，系统会自动展示开关样式。Stepper 绑定数值，文案里实时显示当前值，用户操作时有明确的即时反馈。Picker 在 Form 里有几种表现形态，默认样式在外层没有 NavigationLink 时会自动变成"点击跳转选择页"的样式，但如果你需要"点击弹出菜单"这种更轻量的交互，就显式加 .pickerStyle(.menu)。这个细节后面会专门讲。

录入类的表单也很常见。注册、填写资料时，TextField 是主力：

swift复制Section {
    TextField("请输入昵称", text: $nickname)
        .textInputAutocapitalization(.never)
        .autocorrectionDisabled()
    
    TextField("请输入手机号", text: $phone)
        .keyboardType(.phonePad)
    
    SecureField("请输入密码", text: $password)
} header: {
    Text("账号信息")
} footer: {
    Text("手机号仅用于登录验证")
}

这里有个细节：.textInputAutocapitalization(.never) 和 .autocorrectionDisabled() 对于账号类输入非常关键，不然系统会自动大写首字母、自动纠正用户名，用户会以为是 Bug。.keyboardType 针对不同字段切换键盘类型，手机号用 .phonePad，数字验证码用 .numberPad，小数用 .decimalPad，邮箱用 .emailAddress。

日期类选择也经常出现。DatePicker 在 Form 里要控制粒度：

swift复制DatePicker("出生日期", selection: $birthday, in: ...Date(), displayedComponents: .date)
DatePicker("每日提醒时间", selection: $remindTime, displayedComponents: .hourAndMinute)

.date 只显示年月日，.hourAndMinute 只显示时分。上界用 ...Date() 在 Swift 里是个半开区间写法，表示"只能选今天及以前"。这种写法在表单里很常用，能直接避免用户选出一个未来的生日。

Section 的 header 和 footer 是我特别爱用的部分。header 承担分区标题，footer 承担解释性文案。它的好处是自动化：文案会自动变小号、变灰，不会破坏布局。很多新手会把说明文字直接塞进一行，结果导致行高异常、排版混乱。正确做法是"行内只放控件，说明交给 footer"。

3. 数据绑定与动态表单：让页面真正"活"起来

Form 的静态写法只是基础，真正让它强大的地方在于 SwiftUI 的双向绑定机制。表单页面的本质就是"界面上的控件 ↔ 内存中的数据模型"，绑定写得好，页面自己就活起来了。

最基础的是 @State。它适合管理视图内部的临时状态，比如编辑中的昵称、开关状态：

swift复制@State private var nickname = ""
@State private var pushEnabled = true

这种写法的好处是：TextField 的文本一变，nickname 就跟着变，不需要 delegate、不需要通知、不需要手动赋值。对 SwiftUI 新手来说，最容易犯的错是"在子视图里直接修改父视图的 @State"，应该用 @Binding 把数据传下去：

swift复制struct PushSettingRow: View {
    @Binding var isOn: Bool
    
    var body: some View {
        Toggle("推送开关", isOn: $isOn)
    }
}

如果表单里的设置项需要在 App 重启后保留，直接用 @AppStorage，它会自动持久化到 UserDefaults：

swift复制@AppStorage("pushEnabled") private var pushEnabled = true
@AppStorage("nickname") private var nickname = ""

这一行替代了手动读 UserDefaults + 手动写 UserDefaults 的整个流程。设置页类的表单，我大部分字段都直接 @AppStorage，页面写完，持久化也就写完了，几乎不用单独写存储逻辑。

到了复杂录入场景，比如"新建一条待办"，数据往往涉及多个字段、多个页面。这时候我会把数据封装在 ViewModel 里，用 @StateObject / @ObservedObject 管理。iOS 17 之后新增的 @Bindable 让 ObservableObject 的绑定写法更自然了：

swift复制@Observable
final class ReminderFormModel {
    var title = ""
    var notes = ""
    var isRepeated = false
    var repeatInterval = 1
    var dueDate = Date()
}

struct ReminderFormView: View {
    @State private var model = ReminderFormModel()
    
    var body: some View {
        @Bindable var model = model
        Form {
            Section {
                TextField("标题", text: $model.title)
                TextField("备注", text: $model.notes, axis: .vertical)
            }
            
            Section {
                Toggle("重复提醒", isOn: $model.isRepeated)
                if model.isRepeated {
                    Stepper("每 \(model.repeatInterval) 天", value: $model.repeatInterval, in: 1...30)
                }
            }
            
            Section {
                DatePicker("截止时间", selection: $model.dueDate)
            }
        }
    }
}

注意上面这段用了 @Observable 宏（iOS 17+），配合 @Bindable 在 body 里拿到可绑定的 model，$model.title 才能正常使用。如果你的项目还支持 iOS 16，就需要退回 ObservableObject + @Published + @StateObject 的写法。

动态表单的另外一个核心能力是"条件渲染"。上面的例子已经体现了：当 isRepeated 为 true 时才显示 Stepper。这种动态 Section 让表单可以随时间变化、随用户操作变化，比写死一堆固定字段的体验好太多。我经常用这个套路做"高级设置"折叠：默认只显示基础字段，用户打开一个开关后，隐藏的进阶字段才展开，页面看起来清爽，也降低了新手的认知负担。

还有一个跟动态表单强相关的场景是"提交按钮是否可点击"。比如注册页，只有手机号、密码、验证码全部合法时，"注册"按钮才亮。常见写法是用 onChange 监听字段变化，再去更新一个 canSubmit 状态：

swift复制Form {
    TextField("手机号", text: $phone).keyboardType(.phonePad)
    SecureField("密码", text: $password)
    SecureField("确认密码", text: $confirmPassword)
    
    Button("提交") {
        submit()
    }
    .disabled(!canSubmit)
}
.onChange(of: phone) { _, _ in
    updateCanSubmit()
}
.onChange(of: password) { _, _ in
    updateCanSubmit()
}
.onChange(of: confirmPassword) { _, _ in
    updateCanSubmit()
}

注意 iOS 17 之后 onChange 的闭包签名变成了两个参数（旧值、新值），如果你的最低支持版本是 iOS 16，写 { value in } 单参数还能编译，但 iOS 17 下会报错。我项目里最低支持 iOS 16，所以统一写成 { _, _ in } 双参数写法，编译不报错还能兼顾新版本。这个小坑，后面还要讲一次。

4. 那些文档不会明说的 Form 细节：样式、间距与隐藏背景

Form 默认的 insetGrouped 样式确实好看，但真实项目中几乎总要调整一点边角。这些细节官网不会写，踩过才记得住。

4.1 listStyle 的差异要心里有数

Form 在 iOS 上默认是 .insetGrouped，也就是那种"卡片圆角 + 左右留白"的风格。如果你显式设置了 .listStyle(.grouped)，外观就变成老式列表：卡片之间没有留白、背景色更深、圆角消失。新版 App 里基本不会主动用 .grouped，除非你要做某种复古效果。我的原则是：保持 .insetGrouped，不要动它。

4.2 背景与滚动区域的定制

iOS 16 之后，Form 支持隐藏系统背景：

swift复制Form {
    // ...
}
.scrollContentBackground(.hidden)
.background(Color.customBackground)

这个写法常用来做自定义品牌色背景。但在 iOS 15 及以下没有 scrollContentBackground，需要退而求其次用 UITableView.appearance().backgroundColor 这类旧手段，在 SwiftUI 里属于 hack，能不用就不用。如果你的最低部署版本是 iOS 16+，直接 scrollContentBackground 就好。

4.3 Section 内部边距与分隔线

有些时候你不想要系统默认的分隔线，或者想让某一行紧贴边缘，可以调整 listRowInsets：

swift复制Section {
    HStack {
        Text("自定义卡片")
        Spacer()
    }
    .listRowInsets(EdgeInsets(top: 12, leading: 16, bottom: 12, trailing: 16))
    .listRowSeparator(.hidden)
}

这个 Hack 在 Form 里也是有效的，因为 Form 底层就是基于 List 渲染的。把 listRowSeparator(.hidden) 加在某一行上，这一行的底部分隔线就消失了，适合做"整块卡片感"的行。

4.4 一个容易混的坑：Form 里再套 ScrollView 会怎样

我见过不止一个新手写：

swift复制ScrollView {
    Form { ... }
}

这是错误的。Form 本身就是一个滚动容器，再套一层 ScrollView 会导致滚动冲突：滚动手势会被两层容器抢，表现是"滑动不跟手"或"内部内容被裁切"。正确的做法是：要么只用 Form，要么不用 Form 用 Section 外的自定义布局。如果确实需要"整页滚动 + 底部按钮"，正确姿势是把按钮放进 safeAreaInset（下面讲），而不是把 Form 塞进 ScrollView。

4.5 底部按钮：safeAreaInset 比 Form 内放按钮更合适

表单页底部经常有"保存""提交"按钮。如果你把它作为 Form 的最后一个 Section，键盘弹起时按钮会被键盘顶到不可见区域，用户填完字段根本找不到按钮。我现在的标准做法是：

swift复制Form {
    // 表单字段
}
.safeAreaInset(edge: .bottom) {
    Button("保存") {
        save()
    }
    .buttonStyle(.borderedProminent)
    .padding()
    .background(.bar)
}

这样按钮固定在屏幕底部，键盘弹起时按钮会跟随键盘上方显示，收起时悬浮在底部，交互体验接近原生。这个细节强烈建议直接抄。

4.6 行内图标的渲染位置问题

很多人问"form 的图标存在哪里了"，其实不是图标丢了，而是 Form/List 行里 Image(systemName:) 的渲染模式默认是 template 模式，颜色会跟随环境的 tint 色，所以某些背景下看着像"没图标"或"颜色不对"。想要图标稳定显示出来，最直接的方法是显式指定前景色和渲染模式：

swift复制Label {
    Text("隐私设置")
} icon: {
    Image(systemName: "hand.raised.fill")
        .foregroundColor(.blue)
        .symbolRenderingMode(.monochrome)
}

用 Label 比手动写 HStack { Image; Text } 更好，它天然处理了图标与文字的间距、对齐，并且在 VoiceOver 下会把行作为一个整体朗读。iOS 15+ 的 symbolRenderingMode 可以控制 SF Symbols 是单色、层级色还是多彩，如果图标被系统"脑补"成奇怪颜色，就显式指定 .monochrome。

5. 真实项目里几个反直觉的坑

表单写多了，你会遇到一些"理论上不该出问题"但实际老翻车的地方。我挑几个印象最深的展开讲。

坑 1：Picker 默认样式在外层 NavigationLink 里直接失效

如果你是这么写的：

swift复制Form {
    NavigationLink {
        Picker("城市", selection: $city) {
            Text("北京").tag(0)
            Text("上海").tag(1)
        }
    } label: {
        Text("城市")
    }
}

问题就出现了：Picker 默认在 Form 里已经是"跳转选择页"样式，你再套一层 NavigationLink，等于两层跳转叠加，点击后可能会白屏、闪退，或者选择项无法正确回传。正确做法是二选一：保留 Picker 默认样式（不加 NavigationLink），或者给 Picker 设置 .pickerStyle(.menu) 放在 NavigationLink 里作为行内容。我的习惯是，如果选择项很少（少于 5 个），用 .menu 弹出菜单；如果选择项很多，用默认跳转页样式。

坑 2：TextField 多行输入比想象中麻烦

iOS 16 之前，TextField 在 SwiftUI 里是单行的，用户输入长文本时只会横向滚动，不会换行。想要多行只能上 TextEditor，但 TextEditor 在 Form 里样式很突兀：背景一块白、无法设置占位符。iOS 16 之后 TextField 支持了多行：

swift复制TextField("备注", text: $notes, axis: .vertical)
    .lineLimit(3...6)

这个写法会在 3 到 6 行之间自适应高度。但如果你的最低支持版本是 iOS 15，这段代码无法编译，只能退回 TextEditor 或自定义。项目里如果必须兼容 iOS 15，我会用 TextEditor 加自定义背景：

swift复制TextEditor(text: $notes)
    .frame(minHeight: 80)
    .scrollContentBackground(.hidden) // iOS 16+

坑 3：Form 里大量 TextField 时的性能问题

如果表单里同时有十几个 TextField，每个都绑定了 @State 或 ViewModel 属性，在低端机型上有可能出现滑动卡顿。原因在于每次键盘输入触发文字变化，整个 Form 的 body 会重新求值。优化思路是：把每个输入区块拆成独立的子 View，再传 Binding，缩小更新范围；或者给每个 Section 内的行做稳定 id。我项目里遇到过 8 个 TextField 的设置页在老 iPhone 上滑动掉帧，拆组件之后好了很多。

坑 4：NavigationLink 点击区域太大导致误触

Form 里的一行默认是"整行可点"，有时候只想点击右侧小箭头或某个图标才触发跳转，但实际效果是点行内任意位置都会跳。要限制点击区域，可以在 label 上使用 .contentShape 或直接不用 NavigationLink，改用 Button 配合自定义样式：

swift复制Button {
    navigate()
} label: {
    HStack {
        Text("清理缓存")
        Spacer()
        Image(systemName: "chevron.right")
            .font(.footnote)
            .foregroundColor(.secondary)
    }
}

这样点击区域就是行本身，但你看不到 NavigationLink 的自动箭头，需要手动加一个 chevron.right。两种方式各有取舍：需要与系统外观完全一致的导航指示器，就用 NavigationLink；需要精细控制点击行为与视觉，就用 Button。

坑 5：disabled 加错位置，整行变灰

有时你只想禁用 TextField 输入，但保留文案颜色正常：

swift复制TextField("不可编辑", text: $name)
    .disabled(true)

这段代码只禁用了 TextField 本身，文字不会变灰。但如果你写成：

swift复制Section {
    TextField("不可编辑", text: $name)
}
.disabled(true)

整行包括 label 都会变成灰色的 disabled 外观。所以 .disabled 要加在具体控件上，不要随手挂在 Section 上。

坑 6：键盘工具栏和 return key 的体验

表单页里用户最常做的操作是"填完一个字段，点右下角的下一项"。SwiftUI 里可以用 submitLabel 和 @FocusState 来串联：

swift复制@FocusState private var focusedField: Field?

enum Field: Hashable {
    case nickname
    case phone
    case code
}

TextField("昵称", text: $nickname)
    .focused($focusedField, equals: .nickname)
    .submitLabel(.next)
    .onSubmit {
        focusedField = .phone
    }

TextField("手机号", text: $phone)
    .focused($focusedField, equals: .phone)
    .submitLabel(.next)
    .onSubmit {
        focusedField = .code
    }

TextField("验证码", text: $code)
    .focused($focusedField, equals: .code)
    .submitLabel(.done)

这个链路一旦建立，用户基本不需要用手去点下一个输入框，整个录入流程顺畅很多。@FocusState 在 iOS 14 就有，但很多人写表单时容易忘掉，属于"加上一下体验提升 50%"的细节。

坑 7：onChange 新旧签名混用

前面提过 iOS 17 之后 onChange 签名变了。如果你项目同时跑在 iOS 16 和 iOS 17 上，统一使用双参数闭包 { oldValue, newValue in }，兼容性最好。如果用了 TCA 之类的框架，它内部有更统一的状态管理，但纯 SwiftUI 场景下记住双参数写法就好了。

做完这些处理之后，我现在写表单页的流程基本固定了：先用 Section 按功能分组把字段铺出来，再给每个字段选对应控件和键盘类型，然后加绑定与校验，最后用 safeAreaInset 放底部按钮，跑一遍真机看键盘与滚动体验。这套流程下来，一个中小型表单页大概半天就能交付，而且基本不会出现之前手搓 ScrollView 时那种"改一个需求崩一片布局"的情况。如果遇到系统样式满足不了的定制化设计稿，我的原则是：先确认是不是真的需要自定义，如果只是颜色、圆角、间距这些表面调整，尽量在 Form 体系内用 modifier 完成，这样能保住它免费的交互逻辑和辅助功能支持。