toolbarVisibility

在 SwiftUI 中，toolbarVisibility 是 iOS 16+ 和 macOS 13+ 引入的修饰符，用于控制 导航工具栏的显示与隐藏行为。它允许你根据交互状态（如滚动）或业务逻辑动态调整工具栏的可见性，提升用户体验。

核心功能 #

通过 toolbarVisibility，你可以：

自动隐藏工具栏（如滚动时隐藏）。
全局或局部控制工具栏的显示策略。
适配不同平台（iOS、iPadOS、macOS）的交互习惯。

基本语法 #

// 应用于 NavigationStack 或 NavigationSplitView
NavigationStack {
    ContentView()
}
.toolbarVisibility(.hidden) // 隐藏工具栏

或结合条件动态控制：

@State private var isToolbarVisible = true

NavigationStack {
    ContentView()
}
.toolbarVisibility(isToolbarVisible ? .visible : .hidden)

主要参数 #

参数值	描述
`.automatic`	系统默认行为（如 iOS 滚动时自动隐藏工具栏）
`.visible`	强制显示工具栏
`.hidden`	强制隐藏工具栏

使用场景与示例 #

1. 全局隐藏工具栏 #

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            NavigationStack {
                ContentView()
            }
            .toolbarVisibility(.hidden) // 全局隐藏工具栏
        }
    }
}

2. 滚动时自动隐藏（iOS 默认行为） #

struct ContentView: View {
    var body: some View {
        ScrollView {
            // 长内容列表
        }
        .navigationTitle("列表")
        // iOS 默认在滚动时隐藏导航栏，无需额外代码
    }
}

3. 动态控制工具栏可见性 #

struct DetailView: View {
    @State private var showToolbar = true
    
    var body: some View {
        Text("详情内容")
            .toolbar {
                if showToolbar {
                    ToolbarItem(placement: .primaryAction) {
                        Button("操作") { /* ... */ }
                    }
                }
            }
            .onTapGesture {
                showToolbar.toggle() // 点击切换工具栏显示状态
            }
    }
}

注意事项 #

作用范围
toolbarVisibility 需应用在 导航容器（如 NavigationStack）上，影响其内部所有子视图的工具栏行为。
平台差异
- iOS/iPadOS：滚动时默认隐藏工具栏（.automatic），上滑显示。
- macOS：工具栏通常始终可见，除非显式设置为 .hidden。
与 toolbar 修饰符的配合
即使隐藏工具栏，通过 toolbar { ... } 添加的内容也会被隐藏。若需保留部分按钮，需用条件判断动态渲染。

动画支持
可通过 withAnimation 平滑过渡显示/隐藏：

Button("切换工具栏") {
    withAnimation {
        isToolbarVisible.toggle()
    }
}

完整示例：滚动时隐藏工具栏 #

struct ArticleView: View {
    var body: some View {
        NavigationStack {
            ScrollView {
                VStack(alignment: .leading, spacing: 20) {
                    Text("长篇文章内容...")
                        .frame(maxWidth: .infinity, alignment: .leading)
                }
                .padding()
            }
            .navigationTitle("文章标题")
            .toolbar {
                ToolbarItem(placement: .primaryAction) {
                    Button("收藏") { /* ... */ }
                }
            }
        }
        .toolbarVisibility(.automatic) // 滚动时自动隐藏
    }
}

总结 #

场景	推荐参数	说明
默认交互	`.automatic`	依赖平台自动行为（如滚动隐藏）
强制显示操作按钮	`.visible`	始终显示工具栏
全屏沉浸式体验	`.hidden`	完全隐藏工具栏

通过 toolbarVisibility，你可以灵活控制导航工具栏的展示逻辑，适配不同交互场景和平台规范。