# 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`),並避免不必要的 ViewModel。
- 偏好組合;保持視圖小而專注。
- 使用 async/await 搭配 `.task` 以及明確的載入/錯誤狀態。
- 僅在編輯既有檔案時才維持現有的舊模式。
- 遵循專案的格式化工具與風格指南。
- **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(建議)
```swift
@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 ? "儲存中…" : "儲存") {
Task { await save() }
}
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
新增一個元件參考
- 建立
references/<component>.md。
- 保持簡短且可執行;連結到目前儲存庫中的具體檔案。
- 在
references/components-index.md 中更新新增的項目。