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) } } 
