SwiftUI NavigatorStack 导航容器

NavigationStack 是一个用状态驱动、类型安全的声明式导航容器，它通过管理视图堆栈和导航路径来实现 SwiftUI 应用中的页面导航（专注于单栏场景）

NavigationStack 需要 iOS 16.0+以上版本支持。

核心要素

NavigationStack (导航容器)
    │
    ├── 管理 NavigationPath (状态存储)
    │
    ├── 包含 navigationDestination (路由配置)
    │       │
    │       └── 判断数据类型 → 映射对应的视图
    │
    └── 视图层（导航的起点）

NavigationPath 是导航路径容器，用于管理 NavigationStack 的导航状态和历史记录

navigationDestination 是视图修饰符，用于定义数据类型到目标视图的映射关系，相当于导航系统的路由表

基本用法

1、简单页面跳转

可NavigationStack配合NavigationLink实现（不需要使用NavigationPath记录、管理路径）

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("前往详情页", value: "详情内容")
                NavigationLink("设置", value: "设置页面")
            }
            .navigationDestination(for: String.self) { value in
                DetailView(content: value)
            }
        }
    }
}

struct DetailView: View {
    let content: String
    var body: some View {
        Text("详情: \(content)")
            .navigationTitle("详情页")
    }
}

2、简单页面跳转：多类型路由映射

很多时候，navigationDestination映射的value类型并非只有一种：

struct Test: View {
    var body: some View {
        NavigationStack {
            List {
                // 使用 value 参数 - 必须遵循 Hashable（swift值类型数据默认遵循Hashable协议）
                NavigationLink("使用 value", value: "字符串值")
                NavigationLink("使用数字", value: 42)
            }
            .navigationDestination(for: String.self) { value in
                Text("字符串值: \(value)")
            }
            .navigationDestination(for: Int.self) { value in
                Text("整数值: \(value)")
            }
        }
    }
}

3、简单页面跳转：多类型路由映射2

也可使用枚举管理多种数据类型：

//注意value类型，需要遵循Hashable
enum Route: Hashable {
    case product(Int)
    case profile(String)
    case settings
}

struct MultiTypeNavigationView: View {
    var body: some View {
        NavigationStack {
            VStack(spacing: 20) {
                NavigationLink("产品详情", value: Route.product(123))
                NavigationLink("用户资料", value: Route.profile("张三"))
                NavigationLink("设置", value: Route.settings)
            }
            .navigationDestination(for: Route.self) { route in
                switch route {
                case .product(let id):
                    ProductDetailView(productId: id)
                case .profile(let username):
                    ProfileView(username: username)
                case .settings:
                    SettingsView()
                }
            }
        }
    }
}

4、多层页面跳转

可使用NavigationStack、NavigationPath实现

NavigationPath提供了以下方法用于管理路径：

append() : 跳转到新页面

removeLast(): 返回上一页

removeLast(n): 返回前n页

removeAll(): 返回首页

count: 显示当前导航深度

Codable: 实现状态持久化和深度链接

import SwiftUI

// 定义路由枚举
enum Route: Hashable {
    case detail(String)
    case settings
    case profile(Int)
}

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List {
                Button("跳转到详情页") {
                    path.append(Route.detail("Hello World"))
                }

                Button("跳转到设置") {
                    path.append(Route.settings)
                }

                Button("跳转到用户资料") {
                    path.append(Route.profile(123))
                }

                Button("多层级跳转") {
                    path.append(Route.detail("第一层"))
                    path.append(Route.settings)
                    path.append(Route.profile(456))
                }
            }
            .navigationTitle("首页")
            .navigationDestination(for: Route.self) { route in
                switch route {
                case .detail(let text):
                    DetailView(text: text, path: $path)
                case .settings:
                    SettingsView(path: $path)
                case .profile(let userId):
                    ProfileView(userId: userId, path: $path)
                }
            }
        }
    }
}

struct DetailView: View {
    let text: String
    @Binding var path: NavigationPath

    var body: some View {
        VStack {
            Text("详情页: \(text)")
                .font(.title)

            Button("前往下一层") {
                path.append(Route.detail("从详情页跳转"))
            }

            Button("返回首页") {
                path.removeLast(path.count)
            }

            Button("返回上一层") {
                path.removeLast()
            }
        }
    }
}

struct SettingsView: View {
    @Binding var path: NavigationPath

    var body: some View {
        VStack {
            Text("设置页面")
                .font(.title)

            Button("返回") {
                path.removeLast()
            }
        }
    }
}

struct ProfileView: View {
    let userId: Int
    @Binding var path: NavigationPath

    var body: some View {
        VStack {
            Text("用户资料: \(userId)")
                .font(.title)

            Button("跳转到详情") {
                path.append(Route.detail("来自用户资料"))
            }
        }
    }
}

5、Hashable 的作用

导航必需：NavigationLink 的 value 参数必须遵循 Hashable

路径管理：NavigationPath 依赖 Hashable 来跟踪导航状态

唯一性判断：用于比较两个实例是否代表相同的导航目标

5.1、NavigationLink 的 Hashable 要求

struct NavigationLinkRequirement: View {
    var body: some View {
        NavigationStack {
            List {
                //  形式1：使用 value 参数 - 必须遵循 Hashable
                NavigationLink("使用 value", value: "字符串值")
                NavigationLink("使用数字", value: 42)

                //  这会导致编译错误，因为 MyData 不遵循 Hashable
                // NavigationLink("无效", value: MyData())

                //  形式2：使用 destination 参数 - 不需要 Hashable
                NavigationLink("使用 destination") {
                    MyCustomView()
                }

                //  传统形式 - 不需要 Hashable
                NavigationLink("传统形式", destination: Text("目标视图"))
            }
            .navigationDestination(for: String.self) { value in
                Text("字符串值: \(value)")
            }
            .navigationDestination(for: Int.self) { value in
                Text("整数值: \(value)")
            }
        }
    }
}

//  不遵循 Hashable 的类型
struct MyData {
    let content: String
}

struct MyCustomView: View {
    var body: some View {
        Text("自定义视图")
    }
}

5.2、NavigationPath 的 Hashable 要求

struct NavigationPathExample: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            VStack(spacing: 20) {
                Text("NavigationPath 演示")
                    .font(.title)

                Button("添加字符串") {
                    //  字符串遵循 Hashable
                    path.append("新页面")
                }

                Button("添加整数") {
                    //  整数遵循 Hashable
                    path.append(100)
                }

                Button("添加自定义类型") {
                    //  只要遵循 Hashable 就可以
                    path.append(MyHashableData(name: "测试", id: 1))
                }

                //  这会导致运行时错误
                Button("添加非 Hashable 类型（会崩溃）") {
                    // path.append(MyData()) // 取消注释会崩溃
                }

                Button("查看路径深度: \(path.count)") {
                    print("当前路径深度: \(path.count)")
                }

                Button("返回") {
                    if !path.isEmpty {
                        path.removeLast()
                    }
                }

                Button("返回根视图") {
                    path = NavigationPath() // 重置路径
                }
            }
            .navigationDestination(for: String.self) { value in
                Text("字符串页面: \(value)")
            }
            .navigationDestination(for: Int.self) { value in
                Text("整数页面: \(value)")
            }
            .navigationDestination(for: MyHashableData.self) { data in
                Text("自定义数据: \(data.name) - \(data.id)")
            }
        }
    }
}

//  遵循 Hashable 的自定义类型
struct MyHashableData: Hashable {
    let name: String
    let id: Int
}

6、导航栏UI自定义

NavigationStack 导航结构图：

NavigationStack (容器层)
    │
    ├── ️ NavigationBar (导航栏层)
    │       │
    │       ├── ️ [toolbar: .topBarLeading]
    │       │     ← 返回按钮 / 菜单按钮
    │       │
    │       ├── ️ [navigationTitle]
    │       │     ← 页面标题 (居中显示)
    │       │
    │       └── ️ [toolbar: .topBarTrailing]
    │             ← 编辑按钮 / 更多操作
    │
    └──  Content (内容层)
          ← 你的主要视图内容
          ← 可以独立滚动

NavigationStack {                    // ← 根容器
    ContentView()                    // ←  内容层
        .navigationTitle("标题")     // ← ️ 中央标题
        .toolbar {
            ToolbarItem(placement: .topBarLeading) {  // ← ️ 左侧
                Button("返回") { ... }
            }
            ToolbarItem(placement: .topBarTrailing) { // ← ️ 右侧
                Button("编辑") { ... }
            }
        }
}

自定义导航栏外观，参考案例：

struct CustomNavigationView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("标准页面", value: "standard")
                NavigationLink("自定义标题页面", value: "custom")
                NavigationLink("隐藏导航栏页面", value: "hidden")
            }
            .navigationDestination(for: String.self) { value in
                switch value {
                case "standard":
                    StandardView()
                case "custom":
                    CustomTitleView()
                case "hidden":
                    HiddenNavBarView()
                default:
                    Text("未知页面")
                }
            }
            .navigationTitle("导航演示")
            .toolbar {
                ToolbarItem(placement: .navigationBarTrailing) {
                    Button("设置") {
                        print("设置按钮点击")
                    }
                }
            }
        }
        .tint(.purple) // 统一色调
    }
}

struct StandardView: View {
    var body: some View {
        Text("标准页面")
            .navigationTitle("标准标题")
            .navigationBarTitleDisplayMode(.automatic)
    }
}

struct CustomTitleView: View {
    var body: some View {
        VStack {
            Text("自定义标题页面")

            // 自定义标题视图
            Color.blue
                .frame(height: 200)
                .overlay(
                    Text("大标题")
                        .font(.largeTitle)
                        .foregroundColor(.white)
                )
        }
        .navigationBarTitleDisplayMode(.inline)
        .toolbar {
            ToolbarItem(placement: .principal) {
                VStack {
                    Text("自定义标题")
                        .font(.headline)
                    Text("副标题")
                        .font(.subheadline)
                        .foregroundColor(.secondary)
                }
            }
        }
    }
}

struct HiddenNavBarView: View {
    var body: some View {
        Text("隐藏导航栏页面")
            .navigationBarBackButtonHidden(true)
            .navigationBarHidden(true)
            .toolbar(.hidden, for: .navigationBar)
    }
}