SwiftUI UI Patterns(SwiftUI 界面模式)
快速入门
根据你的目标选择一条路线:
现有项目
- 确定功能或屏幕的主要交互模型(列表、详情、编辑器、设置、标签页)。
- 在仓库中使用
rg "TabView\("或类似命令查找附近示例,然后阅读最接近的 SwiftUI 视图。 - 应用本地约定:优先使用 SwiftUI 原生状态,尽量将状态保持在本地,并使用环境注入共享依赖。
- 从
references/components-index.md中选择相关的组件参考,并遵循其指导。 - 使用小型、专注的子视图和 SwiftUI 原生数据流构建视图。
新项目脚手架搭建
- 从
references/app-scaffolding-wiring.md开始,连接 TabView + NavigationStack + sheets。 - 基于提供的骨架添加一个最小的
AppTab和RouterPath。 - 根据你首先需要的 UI 选择下一个组件参考(TabView、NavigationStack、Sheets)。
- 随着添加新屏幕,扩展路由和 sheet 枚举。
应遵循的通用规则
- 使用现代 SwiftUI 状态(
@State、@Binding、@Observable、@Environment),避免不必要的视图模型。 - 优先使用组合;保持视图小而专注。
- 将 async/await 与
.task结合使用,并明确处理加载/错误状态。 - 仅当编辑遗留文件时才保持现有的遗留模式。
- 遵循项目的格式化和风格指南。
- Sheets:当状态表示选中的模型时,优先使用
.sheet(item:)而非.sheet(isPresented:)。避免在 sheet 主体中使用if let。Sheet 应拥有自己的操作,并在内部调用dismiss(),而不是转发onCancel/onConfirm闭包。
创建新 SwiftUI 视图的工作流程
- 定义视图的状态及其所属位置。
- 通过
@Environment识别要注入的依赖。 - 草拟视图层次结构,并将重复部分提取到子视图中。
- 使用
.task实现异步加载,如有需要则定义明确的状态枚举。 - 当 UI 可交互时,添加无障碍标签或标识符。
- 通过构建验证,并根据需要更新使用点。
组件参考
使用 references/components-index.md 作为入口点。每个组件参考应包括:
- 意图和最佳适用场景。
- 遵循本地约定的最小使用模式。
- 陷阱和性能注意事项。
- 当前仓库中现有示例的路径。
Sheet 模式
Item 驱动的 Sheet(优先)
@State private var selectedItem: Item?
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
}
Sheet 拥有自己的操作
struct EditItemSheet: View {
@Environment(\.dismiss) private var dismiss
@Environment(Store.self) private var store
let item: Item
@State private var isSaving = false
var body: some View {
VStack {
Button(isSaving ? "Saving…" : "Save") {
Task { await save() }
}
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
添加新的组件参考
- 创建
references/<component>.md。 - 保持简短且可操作;链接到当前仓库中的具体文件。
- 用新条目更新
references/components-index.md。