SwiftUI 界面与布局（组件手册）

子视图从上到下排列。页面骨架、表单区块、标题+正文最常用。≈ Compose Column / ArkUI Column。

VStack(
  alignment: HorizontalAlignment = .center,
  spacing: CGFloat? = nil,
  @ViewBuilder content: () -> Content
)

VStack(alignment: .leading, spacing: 12) {
  Text("标题").font(.title.bold())
  Text("副标题").foregroundStyle(.secondary)
  Button("开始") { }
}
.padding()

// spacing: nil → 系统默认间距
VStack { Text("A"); Text("B") }

// spacing: 0 → 紧贴
VStack(spacing: 0) { Text("A"); Text("B") }

子视图从左到右排列。图标+文字、底栏、一行信息。≈ Compose Row / ArkUI Row。

HStack(
  alignment: VerticalAlignment = .center,
  spacing: CGFloat? = nil,
  @ViewBuilder content: () -> Content
)

HStack(alignment: .center, spacing: 8) {
  Image(systemName: "star.fill")
  Text("收藏")
  Spacer()           // 把右边推开，见 Spacer
  Text("12")
}

// 大标题 + 小标注：用基线对齐更整齐
HStack(alignment: .firstTextBaseline, spacing: 4) {
  Text("¥99").font(.largeTitle.bold())
  Text("起").font(.caption).foregroundStyle(.secondary)
}

子视图叠在一起（Z 轴）。写在后面的在上层。典型：背景+内容、头像角标、卡片底+文字。≈ Compose Box / ArkUI Stack。

ZStack(
  alignment: Alignment = .center,
  @ViewBuilder content: () -> Content
)

注意：ZStack 没有 spacing 参数（叠放不谈间距；要用 padding/offset 自己调）。

可以想成手机屏幕上的九个停靠点（中文 LTR）：

// 右上角角标：alignment 用 .topTrailing
ZStack(alignment: .topTrailing) {
  // 下层：背景（先写）
  RoundedRectangle(cornerRadius: 12)
    .fill(.blue.opacity(0.15))
    .frame(height: 120)

  // 中层：主内容
  Text("卡片内容")
    .padding()

  // 上层：角标（后写 → 在最上面）
  Text("NEW")
    .font(.caption2.bold())
    .padding(6)
    .background(.red)
    .foregroundStyle(.white)
    .clipShape(Capsule())
    .padding(8)   // 别贴死边缘
}

// 默认居中叠放
ZStack {
  Circle().fill(.orange).frame(width: 80, height: 80)
  Text("42").bold().foregroundStyle(.white)
}

在 Stack 里贪婪占据剩余空间，把兄弟视图推到两边/两端。

Spacer(minLength: CGFloat? = nil)

• 在 HStack 里：水平方向撑开（左内容 | Spacer | 右内容）
• 在 VStack 里：竖直方向撑开（上内容 / Spacer / 下内容）
• 在 ZStack 里：一般没什么用（叠放不分配轴上剩余空间）
• 多个 Spacer：大致均分剩余空间

HStack {
  Text("左")
  Spacer()                 // 尽量撑开
  Text("右")
}
HStack {
  Text("左")
  Spacer(minLength: 24)    // 最少留 24pt 缝
  Text("右")
}

画一条系统风格的细分割线。

Divider()

无初始化参数。外观靠修饰符或环境间接影响：

VStack {
  Text("上")
  Divider()
  Text("下")
}

内容可能超出屏幕，需要滚动查看。

ScrollView(
  _ axes: Axis.Set = .vertical,
  showsIndicators: Bool = true,
  @ViewBuilder content: () -> Content
)

ScrollView {                 // 默认竖直
  VStack { /* 很长内容 */ }
}
ScrollView(.horizontal, showsIndicators: false) {
  HStack { /* 横向卡片 */ }
}

和 VStack/HStack 排列方式相同，但懒加载：只创建靠近可见区域的子视图。必须放在可滚动容器（通常是 ScrollView）里。

LazyVStack(
  alignment: HorizontalAlignment = .center,
  spacing: CGFloat? = nil,
  pinnedViews: PinnedScrollableViews = .init(),
  @ViewBuilder content: () -> Content
)

LazyHStack(
  alignment: VerticalAlignment = .center,
  spacing: CGFloat? = nil,
  pinnedViews: PinnedScrollableViews = .init(),
  @ViewBuilder content: () -> Content
)

ScrollView {
  LazyVStack(alignment: .leading, spacing: 8, pinnedViews: [.sectionHeaders]) {
    ForEach(0..<200, id: \.self) { i in
      Text("行 \(i)").padding()
    }
  }
}

网格（宫格、相册）。竖向滚动网格用 LazyVGrid；横向用 LazyHGrid。

LazyVGrid(
  columns: [GridItem],
  alignment: HorizontalAlignment = .center,
  spacing: CGFloat? = nil,
  pinnedViews: PinnedScrollableViews = .init(),
  @ViewBuilder content: () -> Content
)

// 固定 3 列
let three = Array(repeating: GridItem(.flexible(), spacing: 12), count: 3)

// 最小 100pt，能排几列排几列
let adaptive = [GridItem(.adaptive(minimum: 100), spacing: 12)]

ScrollView {
  LazyVGrid(columns: adaptive, spacing: 12) {
    ForEach(0..<12, id: \.self) { i in
      RoundedRectangle(cornerRadius: 8)
        .fill(.blue.opacity(0.2))
        .frame(height: 80)
        .overlay(Text("\(i)"))
    }
  }
  .padding()
}

展示只读文字（用户不能直接编辑；要输入用 TextField）。最常见写法：

• Text("你好") —— 固定文案
• Text("你好，\(name)") —— 字符串插值，把变量嵌进文字

下面每一项都是「点在 Text 后面」的链式修饰符：改字体、颜色、行数等。不写则用系统默认。

Text("普通")
Text("加粗").bold()
Text("半粗").fontWeight(.semibold)
Text("标题加粗").font(.title.bold())

Text("主标题")                          // 默认 primary
Text("说明文字").foregroundStyle(.secondary)
Text("错误").foregroundStyle(.red)

Text("这是一段比较长的说明，会自动换行。换行后每一行都左对齐。")
  .multilineTextAlignment(.leading)
  .frame(width: 200)   // 限制宽度才会换行，方便看出效果

Text(longArticle)
  .lineLimit(2)   // 再长也只显示两行，后面变省略号

Text("SwiftUI界面与布局完全入门指南")
  .lineLimit(1)
  .truncationMode(.tail)    // 末尾 …
  // .truncationMode(.middle) // 中间 …

VStack(alignment: .leading, spacing: 8) {
  // 大标题：大号 + 加粗
  Text("今日待办")
    .font(.title.bold())

  // 说明：正文字号 + 灰色次要色 + 最多 3 行 + 多行左对齐
  Text("这里是说明文字，可能会很长很长，超出三行会变成省略号。")
    .font(.body)
    .foregroundStyle(.secondary)
    .multilineTextAlignment(.leading)
    .lineLimit(3)
    .truncationMode(.tail)

  // 插值：把数字嵌进字符串；等宽数字更整齐
  Text("未完成 \(3) 项")
    .font(.title3.monospacedDigit())
    .foregroundStyle(.primary)
}
.padding()

系统推荐的「图标+标题」组合，辅助功能更友好。

Label("标题", systemImage: "gear")
Label("标题", image: "AssetName")          // Assets 图片
Label { Text("标题") } icon: { Image(...) } // 完全自定义

Label("设置", systemImage: "gearshape.fill")
Label("仅图标", systemImage: "heart.fill")
  .labelStyle(.iconOnly)

系统符号或资源图。新手优先 SF Symbols，免切图。

Image(systemName: "wifi")     // SF Symbol
Image("photo")                // Assets.xcassets 中的名字
Image(decorative: "photo")    // 装饰图（辅助功能可忽略）
Image(uiImage: someUIImage)   // 包一层 UIKit 图

HStack(spacing: 16) {
  Image(systemName: "wifi")
    .imageScale(.large)
  Image(systemName: "battery.100")
    .foregroundStyle(.green)
  Image("AppIcon") // Assets 里的名字；示例用系统符号即可
    .resizable()
    .scaledToFit()
    .frame(width: 44, height: 44)
}

点击触发动作。几乎每个界面都有。

Button("标题", action: { /* 点击 */ })
Button("标题", role: .destructive, action: { })
Button(action: { }, label: { /* 自定义外观 */ })
Button("标题", systemImage: "plus") { }   // 较新系统：标题+SF Symbol

VStack(spacing: 12) {
  Button("主操作") { print("go") }
    .buttonStyle(.borderedProminent)
  Button("次要", role: .cancel) { }
    .buttonStyle(.bordered)
  Button("删除", role: .destructive) { }
  Button {
    print("自定义")
  } label: {
    Label("收藏", systemImage: "star")
  }
}

单行输入；密码用 SecureField。

TextField(_ titleKey: String, text: Binding<String>)
TextField(_ titleKey: String, text: Binding<String>, axis: Axis)  // 可竖向扩展的多行（较新）
SecureField(_ titleKey: String, text: Binding<String>)            // 密码，输入变圆点

@State private var email = ""
@State private var pwd = ""
// …
VStack {
  TextField("邮箱", text: $email)
    .keyboardType(.emailAddress)
    .textInputAutocapitalization(.never)
    .textFieldStyle(.roundedBorder)
  SecureField("密码", text: $pwd)
    .textFieldStyle(.roundedBorder)
}

多行文本编辑（笔记、反馈、长描述）。单行输入用 TextField。

TextEditor(text: Binding<String>)

没有 placeholder / 标题参数；占位提示要自己叠一层（见示例）。默认自带系统背景，外观主要靠修饰符。

@State private var note = ""
ZStack(alignment: .topLeading) {
  TextEditor(text: $note)
    .frame(minHeight: 120)
  // 简易占位：内容为空时显示灰字
  if note.isEmpty {
    Text("写点什么…")
      .foregroundStyle(.tertiary)
      .padding(.horizontal, 5)
      .padding(.vertical, 8)
      .allowsHitTesting(false)
  }
}
.overlay(RoundedRectangle(cornerRadius: 8).stroke(.quaternary))

布尔开关。设置页高频。

Toggle(isOn: Binding<Bool>) { /* label */ }
Toggle(_ title: String, isOn: Binding<Bool>)
Toggle(isOn: Binding<Bool>, label: () -> Label)

@State private var notify = true
Toggle("推送通知", isOn: $notify)
Toggle(isOn: $notify) {
  Label("通知", systemImage: "bell")
}

连续数值用 Slider；离散加减用 Stepper。

Slider(
  value: Binding<Double>,
  in: ClosedRange<Double> = 0...1,
  step: Double? = nil,
  onEditingChanged: (Bool) -> Void = { _ in }
)

Stepper(
  "标题",
  value: Binding<Int>,
  in: ClosedRange<Int>,
  step: Int = 1,
  onEditingChanged: (Bool) -> Void = { _ in }
)

@State private var volume = 0.5
@State private var qty = 1
Slider(value: $volume, in: 0...1)
Stepper("数量 \(qty)", value: $qty, in: 1...20)

加载中或进度条。

ProgressView()                      // 转圈，不确定进度
ProgressView("加载中…")             // 转圈 + 文案
ProgressView(value: 0.4)            // 确定进度 0...1
ProgressView(value: 30, total: 100) // 当前/总量
ProgressView(value: 0.4) { Text("下载") } currentValueLabel: { Text("40%") }

ProgressView("请稍候…")
ProgressView(value: 0.35)
  .padding(.horizontal)

点一下用系统浏览器（或合适的 handler）打开 URL。隐私政策、外链、官网常用。App 内页面跳转用 NavigationLink，不要用 Link。

Link(_ title: String, destination: URL)
Link(destination: URL) { /* label View */ }
Link(_ titleKey: LocalizedStringKey, destination: URL)

Link("隐私政策", destination: URL(string: "https://example.com/privacy")!)

Link(destination: URL(string: "https://apple.com")!) {
  Label("打开 Apple", systemImage: "safari")
}

设置页、资料编辑页的标准容器，系统自动分组样式。

Form { ... } —— 无初始化参数；内部用 Section 分组。系统自动给背景、分隔、边距。

Section { /* rows */ }
Section("标题") { /* rows */ }
Section { /* rows */ } header: { Text("头") } footer: { Text("尾") }
Section(isExpanded: $open) { /* iOS 17+ 可折叠 */ }

Form {
  Section("账号") {
    TextField("昵称", text: $name)
    Toggle("公开主页", isOn: $isPublic)
  }
  Section("关于") {
    Text("版本 1.0.0")
  }
}

从枚举/列表里选一个值。

Picker("标题", selection: $selected) {
  ForEach(options) { opt in
    Text(opt.name).tag(opt)   // tag 的类型必须和 selection 一致
  }
}

enum Theme: String, CaseIterable, Identifiable {
  case system, light, dark
  var id: String { rawValue }
}
@State private var theme: Theme = .system
Picker("外观", selection: $theme) {
  ForEach(Theme.allCases) { t in
    Text(t.rawValue).tag(t)
  }
}
.pickerStyle(.segmented)

选日期/时间用 DatePicker；选颜色用 ColorPicker（主题色、标签色）。

DatePicker(
  _ title: String,
  selection: Binding<Date>,
  displayedComponents: DatePickerComponents = [.date, .hourAndMinute]
)
DatePicker(
  _ title: String,
  selection: Binding<Date>,
  in: ClosedRange<Date>,           // 可选：限制可选范围
  displayedComponents: DatePickerComponents
)

ColorPicker(_ title: String, selection: Binding<Color>, supportsOpacity: Bool = true)
ColorPicker(selection: Binding<Color>, supportsOpacity: Bool = true) { /* label */ }

@State private var birthday = Date()
@State private var accent = Color.blue

DatePicker("生日", selection: $birthday, in: ...Date(), displayedComponents: .date)
  .datePickerStyle(.compact)

DatePicker("开会时间", selection: $meeting, displayedComponents: [.date, .hourAndMinute])

ColorPicker("强调色", selection: $accent, supportsOpacity: false)

当背景、头像框、按钮底、描边框。本身是形状，要用 .fill / .stroke 上色，再用 .frame 定大小。

HStack(spacing: 12) {
  Circle().fill(.orange).frame(width: 40, height: 40)

  Capsule()
    .fill(.green.opacity(0.3))
    .frame(width: 80, height: 28)

  RoundedRectangle(cornerRadius: 8, style: .continuous)
    .stroke(.blue, lineWidth: 2)
    .frame(width: 60, height: 40)
}

// 卡片底：填充 + 内描边
RoundedRectangle(cornerRadius: 12)
  .fill(.background)
  .overlay(
    RoundedRectangle(cornerRadius: 12)
      .strokeBorder(.quaternary, lineWidth: 1)
  )
  .frame(height: 100)