SwiftUI 탐색 API 참조
개요
SwiftUI의 탐색 API는 단순한 스택부터 복잡한 다중 열 레이아웃까지 확장 가능한 데이터 중심의 프로그래밍 방식 탐색을 제공합니다. iOS 16(2022)에서 NavigationStack 및 NavigationSplitView로 도입되었고, iOS 18(2024)에서 Tab/Sidebar 통합으로, iOS 26(2025)에서 Liquid Glass 디자인으로 발전했습니다.
발전 타임라인
- 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, 값 기반 NavigationLink
- 2024 (iOS 18) Tab/Sidebar 통합, sidebarAdaptable 스타일, 확대/축소 탐색 전환
- 2025 (iOS 26) Liquid Glass 탐색 크롬, 하단 정렬 검색, 플로팅 탭 바, backgroundExtensionEffect
주요 기능
- 데이터 기반 탐색 NavigationPath는 스택 상태를 나타내어 프로그래밍 방식의 push/pop 및 딥 링킹을 가능하게 합니다.
- 다중 열 레이아웃 NavigationSplitView는 자동으로 적응합니다(iPad에서는 3열 → iPhone에서는 단일 스택).
- 상태 복원 Codable NavigationPath + SceneStorage를 사용하여 앱 실행 간 상태를 유지합니다.
- 탭 통합 탭 전환 시 상태를 유지하는 탭별 NavigationStack (iOS 18+).
- Liquid Glass 자동 유리 탐색 바, 사이드바, 툴바 (iOS 26+).
UIKit과 비교하여 언제 사용할까
- SwiftUI 탐색 새로운 앱, 멀티플랫폼, 간단한 탐색 흐름 → NavigationStack/SplitView 사용
- UINavigationController 복잡한 코디네이터 패턴, 레거시 코드, 특정 UIKit 기능 → UIKit 고려
관련 스킬
axiom-swiftui-nav안티 패턴, 결정 트리, 압박 시나리오에 사용axiom-swiftui-nav-diag탐색 문제의 체계적인 문제 해결에 사용
이 스킬을 사용해야 할 때
다음과 같은 경우 이 스킬을 사용하세요:
- 탐색 API 구현 NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
- 딥 링킹 또는 상태 복원 URL 라우팅, Codable NavigationPath, SceneStorage
- iOS 26+ 기능 채택 Liquid Glass 탐색, 하단 정렬 검색, 탭 바 최소화
- 탐색 아키텍처 선택 Stack vs SplitView vs 코디네이터 패턴
API 진화
타임라인
| 연도 | iOS 버전 | 주요 기능 |
|---|---|---|
| 2020 | iOS 14 | NavigationView (iOS 16에서 deprecated) |
| 2022 | iOS 16 | NavigationStack, NavigationSplitView, NavigationPath, 값 기반 NavigationLink |
| 2024 | iOS 18 | Tab/Sidebar 통합, sidebarAdaptable, TabSection, 확대/축소 전환 |
| 2025 | iOS 26 | Liquid Glass 탐색, backgroundExtensionEffect, tabBarMinimizeBehavior |
NavigationView (Deprecated)
NavigationView는 iOS 16부터 사용이 중단되었습니다. 새 코드에서는 NavigationStack(단일 열 push/pop) 또는 NavigationSplitView(다중 열)만 사용하십시오. 주요 개선 사항: 단일 NavigationPath가 링크별 isActive 바인딩을 대체하고, 값 기반 타입 안전성, 내장 Codable 상태 복원을 제공합니다. "새 탐색 유형으로 마이그레이션" 문서를 참조하세요.
NavigationStack 전체 참조
NavigationStack은 iPhone의 설정 또는 macOS의 시스템 설정과 같은 push-pop 인터페이스를 나타냅니다.
1.1 NavigationStack 생성
기본 NavigationStack
NavigationStack {
List(Category.allCases) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Categories")
.navigationDestination(for: Category.self) { category in
CategoryDetail(category: category)
}
}
경로 바인딩 사용 (WWDC 2022, 6:05)
struct PushableStack: View {
@State private var path: [Recipe] = []
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationStack(path: $path) {
List(Category.allCases) { category in
Section(category.localizedName) {
ForEach(dataModel.recipes(in: category)) { recipe in
NavigationLink(recipe.name, value: recipe)
}
}
}
.navigationTitle("Categories")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.environmentObject(dataModel)
}
}
경로 바인딩 + 값 제공 NavigationLink + navigationDestination(for:)가 핵심 데이터 기반 탐색 패턴을 구성합니다.
1.2 NavigationLink (값 기반)
값 제공 NavigationLink
// 올바름: 값 기반 (iOS 16+)
NavigationLink(recipe.name, value: recipe)
// 올바름: 사용자 정의 레이블 사용
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
// 사용 중단됨: 뷰 기반 (iOS 13-15)
NavigationLink(recipe.name) {
RecipeDetail(recipe: recipe) // 새 코드에서는 사용하지 마세요
}
NavigationLink가 NavigationStack과 함께 작동하는 방식
- NavigationStack은
path컬렉션을 유지합니다. - 값 제공 링크를 탭하면 값이 경로에 추가됩니다.
- NavigationStack은
navigationDestination수정자를 경로 값에 매핑합니다. - 대상 매핑을 기반으로 뷰가 스택에 푸시됩니다.
1.3 navigationDestination 수정자
단일 타입
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
여러 타입
NavigationStack(path: $path) {
RootView()
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
.navigationDestination(for: Category.self) { category in
CategoryList(category: category)
}
.navigationDestination(for: Chef.self) { chef in
ChefProfile(chef: chef)
}
}
탐색 안티 패턴
- 동일한 NavigationStack 계층에서
navigationDestination(for:)와NavigationLink(destination:)를 절대 혼용하지 마세요 — 정의되지 않은 동작을 유발합니다. - 데이터 타입당 한 번
navigationDestination(for:)를 등록하세요 — 중복되면 잘못된 뷰가 나타납니다.
배치 규칙
navigationDestination을 지연 컨테이너 외부에 배치하세요(ForEach 내부가 아님).- 코드 구성을 위해 관련 NavigationLink 근처에 배치하세요.
- NavigationStack 계층 내부에 있어야 합니다.
// 올바름: 지연 컨테이너 외부
ScrollView {
LazyVGrid(columns: columns) {
ForEach(recipes) { recipe in
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
}
}
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
// 잘못됨: ForEach 내부 (로드되지 않을 수 있음)
ForEach(recipes) { recipe in
NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
.navigationDestination(for: Recipe.self) { r in // 이렇게 하지 마세요
RecipeDetail(recipe: r)
}
}
1.4 NavigationPath
NavigationPath는 이기종 탐색 스택을 위한 타입 지워진 컬렉션입니다.
타입 배열 vs NavigationPath
// 타입 배열: 모든 값이 동일한 타입
@State private var path: [Recipe] = []
// NavigationPath: 혼합 타입
@State private var path = NavigationPath()
NavigationPath 연산
// 값 추가
path.append(recipe)
// 이전으로 이동
path.removeLast()
// 루트로 이동
path.removeLast(path.count)
// 또는
path = NavigationPath()
// 개수 확인
if path.count > 0 { ... }
// 딥 링크: 여러 값 설정
path.append(category)
path.append(recipe)
Codable 지원
// 모든 값이 Codable일 때 NavigationPath는 Codable입니다.
@State private var path = NavigationPath()
// 인코딩
let data = try JSONEncoder().encode(path.codable)
// 디코딩
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)
NavigationSplitView 전체 참조
NavigationSplitView는 기기 크기에 적응하는 다중 열 레이아웃을 만듭니다.
2.1 두 열 레이아웃
기본 두 열 (WWDC 2022, 10:40)
struct MultipleColumns: View {
@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
.navigationTitle("Categories")
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Select a recipe")
}
}
}
}
2.2 세 열 레이아웃
사이드바와 세부 정보 사이에 중간 열을 위한 content: 클로저를 추가합니다:
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
} content: {
List(dataModel.recipes(in: selectedCategory), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
} detail: {
RecipeDetail(recipe: selectedRecipe)
}
2.3 NavigationStack과 함께 NavigationSplitView 사용
사이드바 선택을 유지하면서 그리드에서 세부 정보로 드릴다운하기 위해 세부 정보 열 내부에 NavigationStack(path:)를 배치합니다:
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
NavigationStack(path: $path) {
RecipeGrid(category: selectedCategory)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
2.4 열 표시 여부
@State private var columnVisibility: NavigationSplitViewVisibility = .all
NavigationSplitView(columnVisibility: $columnVisibility) {
Sidebar()
} content: {
Content()
} detail: {
Detail()
}
// 프로그래밍 방식으로 표시 여부 제어
columnVisibility = .detailOnly // 사이드바 및 콘텐츠 숨기기
columnVisibility = .all // 모든 열 표시
columnVisibility = .automatic // 시스템이 결정
2.5 자동 적응
NavigationSplitView는 자동으로 적응합니다:
- iPad 가로 모든 열 표시 (구성에 따라 다름)
- iPad 세로/Slide Over 오버레이 또는 단일 열로 축소
- iPhone 단일 탐색 스택
- Apple Watch/TV 단일 탐색 스택
선택 변경은 iPhone에서 push/pop으로 자동 변환됩니다.
2.6 iOS 26+ Liquid Glass 사이드바 (WWDC 2025, 323)
NavigationSplitView {
List { ... }
} detail: {
DetailView()
}
// iPad/macOS에서 사이드바가 자동으로 Liquid Glass 모양을 얻습니다.
// 유리 사이드바 뒤로 콘텐츠 확장
.backgroundExtensionEffect() // 안전 영역 외부의 콘텐츠를 미러링하고 흐리게 합니다.
딥 링킹 및 URL 라우팅
3.1 딥 링크 패턴
.onOpenURL을 사용하여 URL을 수신하고, URLComponents로 구문 분석한 다음, NavigationPath를 조작합니다:
.onOpenURL { url in
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let host = components.host else { return }
path.removeLast(path.count) // 먼저 루트로 이동
// 호스트/경로를 구문 분석하여 대상을 결정한 다음, path.append(value)
}
다중 단계 딥 링크(myapp://category/desserts/recipe/apple-pie)의 경우 URL 경로 구성 요소를 반복하고 각 해결된 값을 추가하여 전체 탐색 스택을 구축합니다.
포괄적인 딥 링킹 예제, 오류 진단 및 테스트 워크플로우는 axiom-swiftui-nav-diag(패턴 3)를 참조하세요.
상태 복원
4.1 완전한 상태 복원 (WWDC 2022, 18:12)
struct UseSceneStorage: View {
@StateObject private var navModel = NavigationModel()
@SceneStorage("navigation") private var data: Data?
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $navModel.selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
.navigationTitle("Categories")
} detail: {
NavigationStack(path: $navModel.recipePath) {
RecipeGrid(category: navModel.selectedCategory)
}
}
.task {
// 나타날 때 복원
if let data = data {
navModel.jsonData = data
}
// 변경 사항 저장
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
.environmentObject(dataModel)
}
}
4.2 Codable NavigationModel
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds // 전체 객체가 아닌 ID 저장
}
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
try container.encode(recipePath.map(\.id), forKey: .recipePathIds)
}
init() {}
required init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.selectedCategory = try container.decodeIfPresent(Category.self, forKey: .selectedCategory)
let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)
self.recipePath = recipePathIds.compactMap { DataModel.shared[$0] } // 삭제된 항목은 무시
}
}
전체 모델 객체 대신 ID를 저장하고 compactMap을 사용하여 삭제된 항목을 정상적으로 처리합니다. 4.1에 표시된 대로 SceneStorage 통합을 위해 jsonData 계산 속성과 objectWillChangeSequence를 추가하세요.
탭 + 탐색 통합
5.1 탭 문법 (iOS 18+) (WWDC 2024, 4:27)
TabView {
Tab("Watch Now", systemImage: "play") {
WatchNowView()
}
Tab("Library", systemImage: "books.vertical") {
LibraryView()
}