SwiftUI NavigationStack：可预测的多步骤流程模式

多步骤流程常出现的问题

多步骤流程是指某一步必须在另一部合理发生之前完成的任何序列。常见示例包括引导（onboarding）、审批请求（审查、确认、提交）以及那种需要跨多个屏幕构建草稿的向导式数据输入。

这些流程看起来简单的前提是“返回（Back）”按用户期望工作。如果返回把他们带到意想不到的地方，用户就会失去对应用的信任。表现为错误提交、放弃引导，以及类似 “我无法回到我之前的屏幕” 的支持工单。

混乱的导航通常表现为下面几种情况之一：

• 应用跳到错误的屏幕，或过早退出流程。
• 同一个屏幕出现两次，因为被推入了两次。
• 某一步在返回时重置，用户丢失他们的草稿。
• 用户能在未完成第 1 步的情况下到达第 3 步，导致无效状态。
• 在深度链接或重启后，应用显示了正确的屏幕，但数据不对。

一个有用的思路：多步骤流程其实是两件事在一起移动。

第一，是一个屏幕栈（用户可以通过返回逐步回到哪里）。第二，是共享的流程状态（草稿数据和进度，不应仅仅因为某个屏幕消失就消失）。

许多 NavigationStack 的实现会在屏幕栈和流程状态发生偏离时崩坏。例如，引导流程可能把“创建个人资料”推入两次（重复路由），而草稿个人资料放在视图内并在重建时被重新创建。用户按返回，看到不同版本的表单，就会认为应用不可靠。

可预测的行为从给流程命名、定义每一步 Back 应该做什么、并把流程状态放在一个明确的位置开始。

你真正需要的 NavigationStack 基础

对于多步骤流程，使用 NavigationStack 而不是旧的 NavigationView。NavigationView 在不同 iOS 版本上行为可能不同，而且在你 push、pop 或恢复屏幕时更难推理。NavigationStack 是现代 API，把导航当成真正的栈来处理。

NavigationStack 会存储用户的历史。每次 push 会向栈中添加一个目的地；每次返回会弹出一个目的地。这个简单的规则让流程感觉稳定：UI 应该反映出一系列清晰的步骤。

栈里真正保存的是什么

SwiftUI 并不是存储你的视图对象，它存储的是你用来导航的数据（你的路由值），并用它在需要时重建目标视图。这带来几个实用的结论：

• 不要依赖视图本身存活来保留重要数据。
• 如果某个屏幕需要状态，把它放在视图外部的模型中（比如 ObservableObject）。
• 如果你两次推入相同目的地但用的是不同数据，SwiftUI 会把它们当作不同的栈条目。

当流程不只是一次或两次固定推送时，NavigationPath 是合适的工具。把它想象成一个可编辑的“我们要去哪里”值列表。你可以 append 路由前进，removeLast 返回，或替换整个路径跳到后面的某一步。

当你需要向导式步骤、在完成后重置流程或想从已保存状态恢复部分流程时，它非常合适。

可预测胜过聪明。更少隐含规则（自动跳转、隐式弹出、由视图驱动的副作用）意味着以后更少奇怪的返回栈 Bug。

用小的路由枚举建模流程

可预测的导航从一个决定开始：把路由集中到一个地方，并让流程里的每个屏幕都是一个小而清晰的值。

创建单一的事实来源，例如一个拥有 NavigationPath 的 FlowRouter（ObservableObject）。这让每次 push 和 pop 保持一致，而不是把导航散落在各个视图中。

一个简单的路由器结构

使用 enum 表示步骤。只在需要轻量级标识符（如 ID）时使用关联值，而不要放入完整模型。

enum Step: Hashable {
    case welcome
    case profile
    case verifyCode(phoneID: UUID)
    case review(applicationID: UUID)
    case done
}

final class FlowRouter: ObservableObject {
    @Published var path = NavigationPath()

    func go(_ step: Step) { path.append(step) }
    func back() { if !path.isEmpty { path.removeLast() } }
    func reset() { path = NavigationPath() }
}

把流程状态和导航状态分开保存

把导航视为“用户在哪里”，把流程状态视为“他们到目前为止输入了什么”。把流程数据放在自己的存储里（例如包含 name、email、uploaded documents 的 OnboardingState），确保它在屏幕出现和消失时保持稳定。

一个简单的经验法则：

• FlowRouter.path 只包含 Step 值。
• OnboardingState 包含用户的输入和草稿数据。
• 步骤携带 ID 来查找数据，而不是携带完整数据。

这样可以避免脆弱的哈希、大路径和在 SwiftUI 重建视图时造成的意外重置。

逐步构建：用 NavigationPath 做向导

对于向导式屏幕，最简单的方法是自己控制栈。目标是：为“我在流程的哪儿？”保留一个事实来源，并且只有一种前进或后退的方式。

从一个绑定到 NavigationPath 的 NavigationStack(path:) 开始。每个被推入的屏幕由一个值表示（通常是枚举 case），并且只注册一次 navigationDestination。

import SwiftUI

enum WizardRoute: Hashable {
    case profile
    case verifyEmail
    case permissions
    case review
}

struct OnboardingWizard: View {
    @State private var path = NavigationPath()
    @State private var currentIndex = 0

    private let steps: [WizardRoute] = [.profile, .verifyEmail, .permissions, .review]

    var body: some View {
        NavigationStack(path: $path) {
            StartScreen {
                goToStep(0) // push first step
            }
            .navigationDestination(for: WizardRoute.self) { route in
                switch route {
                case .profile:
                    ProfileStep(onNext: { goToStep(1) })
                case .verifyEmail:
                    VerifyEmailStep(onNext: { goToStep(2) })
                case .permissions:
                    PermissionsStep(onNext: { goToStep(3) })
                case .review:
                    ReviewStep(onEditProfile: { popToStep(0) })
                }
            }
        }
    }

    private func goToStep(_ index: Int) {
        currentIndex = index
        path.append(steps[index])
    }

    private func popToStep(_ index: Int) {
        let toRemove = max(0, currentIndex - index)
        if toRemove > 0 { path.removeLast(toRemove) }
        currentIndex = index
    }
}

为了保持返回可预测，遵循几个习惯：每次前进只追加一个路由，让“下一步”线性（只 push 下一个步骤），当需要跳回（比如从 Review 的“编辑资料”），修剪栈到已知索引。

这能避免意外的重复屏幕，并让 Back 与用户期望一致：一次点击等于一步。

屏幕出现和消失时保持数据稳定

当每个屏幕拥有自己的状态时，多步骤流程会显得不可靠。你在字段里输入名字、前进、再返回，字段却空了，因为视图被重新创建。

解决方法很直接：把流程当作一个草稿对象，让每个步骤去修改它。

在 SwiftUI 中，通常是在流程开始时创建一个共享的 ObservableObject，并把它传给每一步。除非某个值确实只属于该屏幕，否则别把草稿值放在各视图的 @State 中。

final class OnboardingDraft: ObservableObject {
    @Published var fullName = ""
    @Published var email = ""
    @Published var wantsNotifications = false

    var canGoNextFromProfile: Bool {
        !fullName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
        && email.contains("@")
    }
}

在入口点创建该对象，然后用 @StateObject 或 @EnvironmentObject（或显式传参）共享它。这样栈可以变动而不丢失数据。

决定哪些数据在返回时保留

不是所有东西都应永远保留。提前决定规则让流程保持一致。

保留用户输入（文本字段、开关、选择），除非用户明确重置。重置步骤级别的 UI 状态（加载指示、临时警报、短动画）。离开某步时清除敏感字段（如一次性验证码）。如果某个选择会改变后面的步骤，只清除依赖字段。

校验也应在此处处理。不要让用户进入下一步后再显示错误，让他们停在当前步骤直到有效。基于像 canGoNextFromProfile 这样的计算属性禁用按钮通常足够。

在不滥用的前提下保存检查点

有些草稿只需保存在内存中，另一些则应在应用重启或崩溃后仍存在。一个实用的默认策略：

• 用户在步骤间积极移动时，把数据保存在内存中。
• 在明确的里程碑处持久化（账号创建、审批提交、开始付款）。
• 如果流程很长或数据输入超过一分钟，提前持久化。

这样屏幕可以自由出现和消失，用户的进度仍感觉稳定并尊重他们的时间。

深度链接与恢复部分完成的流程

深度链接很重要，因为真实流程往往不会从第 1 步开始。有人点邮件、推送或共享链接，期望直接到达正确的屏幕，比如引导的第 3 步或最终审批屏幕。

使用 NavigationStack 时，把深度链接当作构建合法路径的指令，而不是跳到某个视图的命令。应从流程开始，并只追加对该用户和会话真实有效的步骤。

把外部链接转成安全的路由序列

一个好的模式是：解析外部 ID，加载最少必要的数据，然后把它转换为路由序列。

enum Route: Hashable {
    case start
    case profile
    case verifyEmail
    case approve(requestID: String)
}

func pathForDeepLink(requestID: String, hasProfile: Bool, emailVerified: Bool) -> [Route] {
    var routes: [Route] = [.start]
    if !hasProfile { routes.append(.profile) }
    if !emailVerified { routes.append(.verifyEmail) }
    routes.append(.approve(requestID: requestID))
    return routes
}

这些检查是你的保护措施。如果前置条件缺失，不要把用户直接放到第 3 步并抛错。引导他们到第一个缺失的步骤，确保返回栈仍然讲得通。

恢复部分完成的流程

要在重启后恢复，保存两件事：最后已知的路由状态和用户输入的草稿数据。然后决定如何在不让人惊讶的情况下恢复。

如果草稿是最近的（几分钟或几小时内），提供一个明显的 “恢复” 选项。如果草稿很旧，从头开始但用草稿预填字段通常比把用户直接放回中间更合理。如果需求改变，用相同的前置检查重建路径。

Push 与模态：让流程易于退出

流程可预测的表现之一是有一条主要的继续路径：在单个栈上 push 屏幕。把 sheets 和 full-screen covers 用于旁支任务，而不是主路径。

Push（NavigationStack）适合用户期望通过 Back 逐步回退的场景。模态（sheet 或 fullScreenCover）适合用户执行子任务、快速选择或确认高风险操作。

一组简单规则可以避免大多数导航混乱：

• 主路径使用 push（Step 1、Step 2、Step 3）。
• 可选的小任务使用 sheet（选择日期、国家、扫描文档）。
• 独立体验使用 fullScreenCover（登录、相机捕获、长的法律文档）。
• 确认类操作使用模态（取消流程、删除草稿、提交审批）。

常见错误是把主流程屏幕放进 sheet。如果第 2 步是 sheet，用户可以通过滑动消失它、丢失上下文，造成栈显示仍在第 1 步而数据却表明他们完成了第 2 步。

确认类对话则相反：把“你确定吗？”屏幕推入向导会让栈混乱并可能形成循环（Step 3 -> Confirm -> Back -> Step 3 -> Back -> Confirm）。

完成后如何整洁地关闭所有内容

先决定“完成（Done）”的含义：返回首页、返回列表，还是显示成功页。

如果流程是 push 的，重置你的 NavigationPath 为空以弹回到起点。如果流程以模态展示，使用环境的 dismiss()。如果两者都有（模态内有 NavigationStack），关闭模态，而不是逐个弹出每个 push。成功提交后也要清除草稿状态，以便重新打开流程时是新的开始。

返回按钮行为与“确定要离开？”时刻

对于大多数多步骤流程，最好的做法是让系统处理：让系统的返回按钮（和滑动返回手势）正常工作。这匹配用户预期，并避免 UI 显示一种状态而导航状态是另一种的 Bug。

只有在返回会造成实际伤害（例如丢失长时间未保存的表单或放弃不可逆操作）时，才值得拦截。如果用户可以安全返回并继续，就不要增加摩擦。

实用做法是保留系统导航，但仅在屏幕“已编辑”（dirty）时才添加确认。这意味着提供自己的后退行为并只询问一次，同时给出明确的退出方式。

@Environment(\.dismiss) private var dismiss
@State private var showLeaveConfirm = false
let hasUnsavedChanges: Bool

var body: some View {
  Form { /* fields */ }
    .navigationBarBackButtonHidden(hasUnsavedChanges)
    .toolbar {
      if hasUnsavedChanges {
        ToolbarItem(placement: .navigationBarLeading) {
          Button("Back") { showLeaveConfirm = true }
        }
      }
    }
    .confirmationDialog("Discard changes?", isPresented: $showLeaveConfirm) {
      Button("Discard", role: .destructive) { dismiss() }
      Button("Keep Editing", role: .cancel) {}
    }
}

避免这变成陷阱：

• 只有在你能用一句话解释后果时才询问。
• 提供一个安全选项（取消、继续编辑）和一个明确的退出（丢弃、离开）。
• 除非你用明显的 Back 或 Close 替代，否则不要隐藏返回按钮。
• 对于不可逆操作（如“批准”），优先对该不可逆操作做确认，而不是到处阻止导航。

如果你经常与返回手势作斗争，通常说明流程需要自动保存、保存草稿或把步骤拆得更小。

导致奇怪返回栈的常见错误

大多数“它为什么会回到那里？”的 Bug 并不是 SwiftUI 随机行为。通常是一些会使导航状态不稳定的模式。为了可预测，把返回栈当作应用数据：稳定、可测试，并由一个地方拥有。

意外的额外栈

一个常见陷阱是不知不觉中创建了多个 NavigationStack。例如，每个 tab 有自己的根栈，然后子视图在流程内又加了一个栈。结果是混乱的返回行为、缺失的导航栏或屏幕无法按预期弹出。

另一个常见问题是频繁重新创建你的 NavigationPath。如果 path 在会重新渲染的视图里创建，它可能在状态改变时重置，使用户在输入字段时被跳回到第 1 步。

造成大多数奇怪栈行为的错误包括：

• 在另一个栈内再嵌套 NavigationStack（常见于 tabs 或 sheet 内容）
• 在视图更新时重新初始化 NavigationPath()，而不是把它放在长期存在的状态里
• 在路由中放入不稳定的值（例如会变化的模型对象），这会破坏 Hashable 并导致目的地不匹配
• 把导航决策散落在各个按钮处理器中，直到没人能解释“下一步”是什么意思
• 让多个来源同时驱动流程（例如 view model 和 view 都修改 path）

如果需要在步骤间传递数据，优先在路由中使用稳定的标识符（ID、步骤枚举），并把实际表单数据放在共享状态中。

一个具体例子：如果你的路由是 .profile(User)，而 User 在输入时变化，SwiftUI 会把它当作不同路由并重建栈。改成 .profile，把草稿 User 存在共享状态中。

可预测导航的快速检查清单

当流程感觉不对时，通常是因为返回栈在讲述的故事与用户看到的不一致。在打磨 UI 之前，快速检查你的导航规则。

在真机上测试，不只用预览，并尝试快和慢点击。快速点击常会暴露重复 push 和缺失状态的问题。

• 从最后一屏一步步返回到第一屏。确认每个屏幕显示的都是用户之前输入的数据。
• 在每一步触发 Cancel（包括第一步和最后一步）。确认总是返回到合理的位置，而不是某个随机先前屏幕。
• 在流程中强制退出并重启。确认可以安全恢复，要么恢复路径，要么从已知步骤重新开始并填充已保存数据。
• 用深度链接或应用快捷方式打开流程。验证目标步骤有效；如果缺少必要数据，重定向到能收集这些数据的最早步骤。
• 完成后按 Done 并确认流程已被干净移除。用户不应能按 Back 再进入已完成的向导。

一个简单的测试方法：想象一个有三个屏幕（Profile、Permissions、Confirm）的引导向导。输入名字，前进，返回，编辑，然后通过深度链接跳到 Confirm。如果 Confirm 显示旧名字，或返回把你带到重复的 Profile 屏幕，说明你的路径更新不一致。

如果你能通过这些检查而没有惊讶，用户即使离开再回来，流程也会显得平稳可预测。

一个现实的示例与后续步骤

设想一个用于报销请求的经理审批流程，有四个步骤：Review、Edit、Confirm 和 Receipt。用户期望的是：Back 总是回到上一步，而不是回到他们之前访问过的某个随机屏幕。

一个简单的路由枚举可以保持这一点的可预测性。你的 NavigationPath 应只保存路由和任何用于重新加载状态的小标识符，比如 expenseID 和 mode（review vs edit）。避免把大型、可变的模型放进路径，因为那会让恢复和深度链接变脆弱。

把工作草稿放在视图外的单一事实来源，例如作为一个 @StateObject 的流程模型（或一个 store）。每个步骤读写该模型，这样屏幕可以出现和消失而不丢失输入。

至少你需要跟踪三件事：

• 路由（例如：review(expenseID)、edit(expenseID)、confirm(expenseID)、receipt(expenseID)）
• 数据（带有明细和备注的草稿对象，以及诸如 pending、approved、rejected 之类的状态）
• 位置（流程模型内的草稿、服务器上的规范记录，以及本地的小恢复令牌：expenseID + last step）

边缘情况往往决定流程是赢得信任还是失去信任。例如，如果经理在 Confirm 驳回，决定返回 Edit 以便修正还是退出流程。如果他们以后再来，使用保存的令牌恢复上次步骤并重新加载草稿。若换设备，以服务器为准：从服务器状态重建路径并把用户送到正确的步骤。

接下来的步骤：为你的路由枚举写清楚文档（每个 case 的含义和使用场景），为路径构建和恢复行为添加几条基本测试，并坚持一个规则：视图不拥有导航决策。

如果你不想从零开始构建这些多步骤流程，像 AppMaster (appmaster.io) 这样的平台也采用相同的分离原则：把步骤导航和业务数据分开，这样屏幕可以改变而不会破坏用户的进度。