swiftui-ui-patterns

SwiftUI UI 模式

快速开始

根据你的目标选择一条路径：

现有项目

• 确定功能或界面，以及主要交互模式（列表、详情、编辑器、设置、标签页）。
• 使用 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），避免不必要的视图模型。
• 优先使用组合；保持视图小巧且专注。
• 使用 .task 配合 async/await，并明确处理加载和错误状态。
• 仅在编辑旧版文件时保留现有旧版模式。
• 遵循项目的格式化工具和风格指南。
• Sheets：当状态表示一个选中的模型时，优先使用 .sheet(item:)，而不是 .sheet(isPresented:)。避免在 sheet 主体中使用 if let。Sheet 应自行管理操作，并在内部调用 dismiss()，而不是转发 onCancel/onConfirm 闭包。

新建 SwiftUI 视图的工作流

1. 定义视图的状态及其所属位置。
2. 确定要通过 @Environment 注入的依赖项。
3. 规划视图层级，并将重复部分提取为子视图。
4. 使用 .task 实现异步加载；如有需要，使用明确的状态枚举。
5. 当 UI 可交互时，添加无障碍标签或标识符。
6. 通过构建进行验证，并在需要时更新使用该视图的调用点。

组件参考

将 references/components-index.md 作为入口。每份组件参考应包含：

• 意图和最适用的场景。
• 遵循本地约定的最简用法。
• 常见问题和性能说明。
• 当前仓库中现有示例的路径。

Sheet 模式

由项目驱动的 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 中添加新条目。

Apple 官方文档

参考以下文档，了解最新的 SwiftUI API 和集成模式：

• references/SwiftUI-WebKit-Integration.md - 在 SwiftUI 中集成 WebKit 视图的官方指南
• references/SwiftUI-Styled-Text-Editing.md - SwiftUI 中的富文本编辑与样式设置
• references/SwiftUI-New-Toolbar-Features.md - 最新的工具栏自定义功能与特性
• references/SwiftUI-AlarmKit-Integration.md - AlarmKit 集成模式与示例

这些文档包含 iOS 26+ 功能的 Apple 官方模式；实现相关功能时应查阅这些文档。