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)를 선택합니다.
- 새 화면이 추가됨에 따라 경로 및 시트 열거형을 확장합니다.
따라야 할 일반 규칙
- 최신 SwiftUI 상태(
@State,@Binding,@Observable,@Environment)를 사용하고 불필요한 뷰 모델을 피합니다. - 컴포지션을 선호하고, 뷰를 작고 집중적으로 유지합니다.
.task와 함께 async/await를 사용하고 명시적인 로딩/오류 상태를 표시합니다.- 레거시 파일을 편집할 때만 기존 레거시 패턴을 유지합니다.
- 프로젝트의 포맷터 및 스타일 가이드를 따릅니다.
- 시트: 상태가 선택된 모델을 나타낼 때는
.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에 새 항목을 업데이트합니다.