SwiftUI中navigationBarTitleDisplayMode与toolbarTitleDisplayMode的区别及API疑问

一、核心功能差异 #

• 适配的导航架构不同

  • navigationBarTitleDisplayMode是为旧版NavigationView（iOS 13+）设计的API，仅支持.large、.inline、.automatic三种显示模式，完全贴合传统导航栏的布局逻辑。
  • toolbarTitleDisplayMode是苹果针对新版NavigationStack/NavigationSplitView（iOS 16+）推出的新API，除了兼容旧的三种模式，还新增了.inlineLarge模式——这种模式能让内联标题用上大标题的字号，但保持内联的布局位置，同时它还能配合toolbarTitleMenu实现标题下拉菜单，这是前者完全不支持的。

• 标题设置的统一逻辑
  两者都必须配合navigationTitle使用，没有单独的toolbarTitleAPI，因为苹果希望统一标题的设置入口，仅在显示模式的控制逻辑上做区分。

二、为什么同时保留两个API？ #

1. 旧架构兼容性需求
   虽然苹果推荐迁移到NavigationStack，但iOS 16+依然支持NavigationView，navigationBarTitleDisplayMode是它的专属配置API，若在旧导航视图中使用toolbarTitleDisplayMode不会生效，因此必须保留给尚未完成迁移的项目。
2. 功能迭代的分层设计
   toolbarTitleDisplayMode是旧API的升级版本，整合了现代导航栈的新特性，但旧API不能直接废弃——否则大量依赖NavigationView的旧项目会出现适配问题，苹果需要给开发者留足迁移过渡的时间。

三、和navigationBarTitle废弃的关联 #

这两者直接相关：

• 旧版的navigationBarTitle(_:displayMode:)被废弃后，拆分成了navigationTitle(_:)（统一设置标题文本）和navigationBarTitleDisplayMode(_:)（控制旧导航栏的显示模式）两个独立API。
• 当苹果推出NavigationStack这种新导航架构时，需要一个能承载更多新特性的显示模式控制API，于是toolbarTitleDisplayMode应运而生——它本质上是旧API的迭代，但因为旧导航架构还未被彻底移除，所以两个API必须同时存在。

代码示例 #

struct ContentView: View {
    var body: some View {
        // 新版导航栈：支持toolbarTitleDisplayMode的全部特性
        NavigationStack {
            Text("Hello, world!")
                .navigationTitle("Hello")
                .toolbarTitleDisplayMode(.inlineLarge)
                .toolbarTitleMenu {
                    Button("选项1") {}
                    Button("选项2") {}
                }
        }
        
        // 旧版导航视图：只能用navigationBarTitleDisplayMode
        NavigationView {
            Text("旧版视图")
                .navigationTitle("Legacy")
                .navigationBarTitleDisplayMode(.inline)
        }
    }
}

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