名称： swiftui-ui-patterns
描述： 构建 SwiftUI 视图与组件的最佳实践与示例驱动指南。适用于创建或重构 SwiftUI UI、使用 TabView 设计标签页架构、组合屏幕，或需要特定组件模式与示例的场景。

SwiftUI UI 模式

快速开始

根据你的目标选择路径：

现有项目

• 确定功能或屏幕以及主要的交互模式（列表、详情、编辑器、设置、标签页）。
• 在代码库中使用 rg "TabView\(" 或类似命令查找相近示例，然后阅读最接近的 SwiftUI 视图。
• 应用本地约定：优先使用 SwiftUI 原生状态管理，尽可能保持状态局部化，并使用环境注入共享依赖。
• 从 references/components-index.md 中选择相关的组件参考并遵循其指导。
• 使用小型、专注的子视图和 SwiftUI 原生数据流来构建视图。

新项目脚手架

• 从 references/app-scaffolding-wiring.md 开始，以连接 TabView + NavigationStack + 模态视图。
• 基于提供的骨架代码，添加一个最小的 AppTab 和 RouterPath。
• 根据你首先需要的 UI，选择下一个组件参考（TabView、NavigationStack、模态视图）。
• 随着新屏幕的添加，扩展路由和模态视图的枚举。

通用规则

• 使用现代 SwiftUI 状态管理（@State、@Binding、@Observable、@Environment），避免不必要的视图模型。
• 优先采用组合方式；保持视图小巧且专注。
• 结合 .task 使用 async/await，并显式处理加载/错误状态。
• 仅在编辑遗留文件时，才沿用现有的遗留模式。
• 遵循项目的代码格式化工具和风格指南。
• 模态视图：当状态表示一个被选中的模型时，优先使用 .sheet(item:) 而非 .sheet(isPresented:)。避免在模态视图主体内使用 if let。模态视图应拥有其操作，并在内部调用 dismiss()，而不是转发 onCancel/onConfirm 闭包。

创建新 SwiftUI 视图的工作流

1. 定义视图的状态及其所有权位置。
2. 识别需要通过 @Environment 注入的依赖项。
3. 勾勒视图层次结构，并将重复部分提取为子视图。
4. 如有需要，使用 .task 和显式的状态枚举来实现异步加载。
5. 当 UI 具有交互性时，添加无障碍标签或标识符。
6. 进行构建验证，并根据需要更新调用点。

组件参考

以 references/components-index.md 为入口点。每个组件参考应包含：
- 意图与最佳适用场景。
- 结合本地约定的最小化使用模式。
- 常见陷阱与性能注意事项。
- 指向当前代码库中现有示例的路径。

模态视图模式

基于项的模态视图（推荐）

@State private var selectedItem: Item?

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
}

模态视图拥有其操作

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 ? "保存中…" : "保存") {
                Task { await save() }
            }
        }
    }

    private func save() async {
        isSaving = true
        await store.save(item)
        dismiss()
    }
}

添加新的组件参考

• 创建 references/<组件名>.md。
• 保持内容简洁且可操作；链接到当前代码库中的具体文件。
• 在 references/components-index.md 中更新新条目。