SwiftUI NavigationStack 완전 정복 (push, pop, 딥링크까지 한 번에 해결)

SwiftUI NavigationStack 완전 정복 (push, pop, 딥링크까지 한 번에 해결)

SwiftUI에서 가장 많이 막히는 영역은 단연 Navigation입니다. 특히 NavigationStack은 단순해 보이지만, 실무에서는 push, pop, 딥링크, 상태 관리까지 얽히면서 복잡해집니다.

이 글 하나로 NavigationStack의 핵심을 전부 정리합니다.

---

1. NavigationStack 기본 구조

struct ContentView: View {
    @State private var path: [Int] = []

    var body: some View {
        NavigationStack(path: $path) {
            VStack {
                Button("Go to Detail") {
                    path.append(1)
                }
            }
            .navigationDestination(for: Int.self) { value in
                Text("Detail \(value)")
            }
        }
    }
}

핵심은 단 하나입니다.

NavigationStack은 path 배열로 화면을 관리한다

---

2. Push (화면 이동)

push는 path에 데이터를 추가하면 됩니다.

path.append(1)

• 배열에 값 추가 → 화면 push
• navigationDestination에서 해당 타입 처리

---

3. Pop (뒤로가기)

한 단계 뒤로

path.removeLast()

루트로 이동

path.removeAll()

UIKit과 다르게 navigationController 없이 데이터 기반으로 제어합니다.

---

4. 다양한 화면 타입 처리

enum Route: Hashable {
    case home
    case detail(Int)
    case profile(String)
}

@State private var path: [Route] = []

.navigationDestination(for: Route.self) { route in
    switch route {
    case .home:
        HomeView()
    case .detail(let id):
        DetailView(id: id)
    case .profile(let name):
        ProfileView(name: name)
    }
}

실무에서는 enum으로 관리하는 것이 가장 안전합니다.

---

5. 딥링크 처리

앱 실행 시 특정 화면으로 이동하려면 path를 초기값으로 설정하면 됩니다.

.onAppear {
    path = [.detail(3)]
}

푸시, URL 스킴, Universal Link 모두 동일한 방식으로 처리 가능합니다.

---

6. NavigationStack에서 자주 발생하는 문제

1) push가 안 되는 경우

• navigationDestination 누락
• Hashable 미구현

2) 화면이 중복 push되는 경우

• 중복 append

3) 뒤로가기 제어 안 되는 경우

• path 관리 안 하고 NavigationLink만 사용

---

7. 실무 추천 구조

단순 배열보다 다음 구조가 더 안정적입니다.

class Router: ObservableObject {
    @Published var path: [Route] = []

    func push(_ route: Route) {
        path.append(route)
    }

    func pop() {
        path.removeLast()
    }

    func popToRoot() {
        path.removeAll()
    }
}

View에서는 Router를 주입해서 사용합니다.

---

8. NavigationStack vs NavigationLink

구분	NavigationLink	NavigationStack
방식	View 기반	데이터 기반
제어	제한적	완전 제어 가능
딥링크	어려움	가능

---

9. 결론

NavigationStack의 핵심은 이것입니다.

화면 이동은 UI가 아니라 상태(state)로 관리한다

• push → path.append
• pop → path.removeLast
• 딥링크 → path 초기값 설정

이 구조를 이해하면 복잡한 네비게이션도 안정적으로 구현할 수 있습니다.

---

다음 글에서는 SwiftUI 상태 관리 (@State, @Binding, @ObservedObject)를 다루면 Navigation과 함께 완전한 구조를 만들 수 있습니다.