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 檢視的工作流程
- 定義檢視的狀態及其所有權位置。
- 識別要透過
@Environment注入的依賴。 - 草擬檢視的階層結構,並將重複的部分抽取成子檢視。
- 使用
.task實作非同步載入,必要時加上明確的狀態列舉。 - 當 UI 可互動時,加入輔助使用標籤或識別碼。
- 進行建置驗證,並在必要時更新使用端點。
元件參考
使用 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 ? "儲存中…" : "儲存") {
Task { await save() }
}
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
新增元件參考
- 建立
references/<component>.md。 - 保持簡短且可執行;連結到當前儲存庫中的具體檔案。
- 使用新的條目更新
references/components-index.md。