iOS17隐藏导航栏侧滑返回后再次进入详情页卡顿问题排查

问题背景 #

在隐藏导航栏的SwiftUI视图中，通过全局扩展UINavigationController并设置interactivePopGestureRecognizer代理来启用侧滑返回功能。该操作在iOS16中正常，但在iOS17中出现异常：侧滑返回主界面后再次进入详情页会出现界面卡顿，且尝试将代理设置从viewDidLoad移至viewWillAppear后问题仍未解决。

示例代码：

struct ContentView: View {
    var body: some View {
        NavigationStack {
            NavigationLink(destination: DetailView()) {
                Text("Go to Detail")
            }
            .navigationTitle("Main")
        }
    }
}

struct DetailView: View {
    var body: some View {
        Text("Detail View")
            .toolbar(.hidden, for: .navigationBar)
    }
}

extension UINavigationController: UIGestureRecognizerDelegate {
    open override func viewDidLoad() {
        super.viewDidLoad()
        interactivePopGestureRecognizer?.delegate = self
    }
}

原因分析 #

iOS17对SwiftUI的NavigationStack底层实现做了调整，其与UIKit的UINavigationController交互逻辑发生变化：

• 全局扩展UINavigationController并强制设置手势代理，会破坏SwiftUI原生的手势协调机制，导致手势识别器的状态管理混乱。
• 当导航栏隐藏的页面返回主界面后，iOS17中未正确重置手势代理关联的视图状态，再次进入详情页时，手势识别器与视图渲染流程发生冲突，进而引发卡顿。

解决方法 #

方法一：移除全局扩展，使用SwiftUI原生侧滑返回配置 #

iOS17中，即使隐藏导航栏，侧滑返回功能默认支持，无需通过UIKit代理强制开启。若默认不可用，可通过自定义手势结合dismiss动作实现：

struct DetailView: View {
    @Environment(\.dismiss) private var dismiss
    
    var body: some View {
        Text("Detail View")
            .toolbar(.hidden, for: .navigationBar)
            .gesture(
                DragGesture(minimumDistance: 30, coordinateSpace: .global)
                    .onEnded { value in
                        if value.translation.width > 50 {
                            dismiss()
                        }
                    }
            )
    }
}

方法二：局部设置手势代理，避免全局干扰 #

若必须依赖UIKit的手势代理，不要全局扩展UINavigationController，而是在目标页面的生命周期内临时设置并在离开时重置：

struct DetailView: View {
    private var navController: UINavigationController? {
        UIApplication.shared.connectedScenes
            .compactMap { $0 as? UIWindowScene }
            .first?.windows
            .first?.rootViewController as? UINavigationController
    }
    
    var body: some View {
        Text("Detail View")
            .toolbar(.hidden, for: .navigationBar)
            .onAppear {
                navController?.interactivePopGestureRecognizer?.delegate = navController
            }
            .onDisappear {
                navController?.interactivePopGestureRecognizer?.delegate = nil
            }
    }
}

方法三：使用自定义NavigationController子类 #

创建自定义UINavigationController子类，仅在需要的场景中使用，避免影响全局导航栈：

class CustomNavigationController: UINavigationController, UIGestureRecognizerDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        interactivePopGestureRecognizer?.delegate = self
    }
    
    func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
        // 仅当导航栈中有多个页面时允许侧滑返回
        return viewControllers.count > 1
    }
}

// 在SwiftUI中包装自定义导航控制器
struct NavigationStackWrapper<Content: View>: UIViewControllerRepresentable {
    let content: Content
    
    func makeUIViewController(context: Context) -> CustomNavigationController {
        let hostingController = UIHostingController(rootView: content)
        let navController = CustomNavigationController(rootViewController: hostingController)
        return navController
    }
    
    func updateUIViewController(_ uiViewController: CustomNavigationController, context: Context) {}
}

// 修改ContentView使用自定义导航容器
struct ContentView: View {
    var body: some View {
        NavigationStackWrapper {
            NavigationLink(destination: DetailView()) {
                Text("Go to Detail")
            }
            .navigationTitle("Main")
        }
    }
}

内容的提问来源于stack exchange，提问作者hjazz