SwiftUI UI 패턴
빠른 시작
목표에 따라 트랙을 선택하세요:
기존 프로젝트
- 기능 또는 화면과 기본 상호작용 모델(목록, 상세, 편집기, 설정, 탭)을 식별합니다.
rg "TabView\("등으로 저장소에서 비슷한 예제를 찾은 다음, 가장 가까운 SwiftUI 뷰를 읽습니다.- 로컬 규칙을 적용합니다: SwiftUI 네이티브 상태를 선호하고, 가능하면 상태를 로컬로 유지하며, 공유 종속성에는 환경(Environment) 주입을 사용합니다.
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를 사용합니다.- 기존 레거시 파일을 편집할 때만 기존 레거시 패턴을 유지합니다.
- 프로젝트의 포매터 및 스타일 가이드를 따릅니다.
- 시트(Sheets): 상태가 선택된 모델을 나타낼 때는
.sheet(isPresented:)보다.sheet(item:)을 선호합니다. 시트 본문에서if let을 사용하지 마세요. 시트는 자체 작업을 소유하고onCancel/onConfirm클로저를 전달하는 대신 내부적으로dismiss()를 호출해야 합니다.
새 SwiftUI 뷰 작업 흐름
- 뷰의 상태와 그 소유권 위치를 정의합니다.
@Environment를 통해 주입할 종속성을 식별합니다.- 뷰 계층 구조를 스케치하고 반복되는 부분을 하위 뷰로 추출합니다.
.task와 필요한 경우 명시적 상태 열거형을 사용하여 비동기 로딩을 구현합니다.- UI가 상호작용할 때 접근성 레이블 또는 식별자를 추가합니다.
- 빌드로 검증하고 필요한 경우 사용처를 업데이트합니다.
컴포넌트 참조
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/<component>.md를 생성합니다.- 짧고 실행 가능하게 유지하며, 현재 저장소의 구체적인 파일에 링크합니다.
- 새 항목으로
references/components-index.md를 업데이트합니다.