toolbarBackgroundVisibility

在 SwiftUI 中，toolbarBackgroundVisibility 是 iOS 16+ 和 macOS 13+ 引入的修饰符，专门用于控制 工具栏背景的显示与隐藏。与 toolbarVisibility（控制工具栏整体可见性）不同，它允许你独立管理工具栏的背景样式（如颜色、材质）及其可见性，常用于实现动态背景效果（如滚动时渐隐背景）。

核心作用 #

通过 toolbarBackgroundVisibility，可以：

动态隐藏/显示工具栏背景（如滚动时隐藏背景，内容沉浸式展示）。
为不同平台设置背景可见性策略（iOS、macOS 等）。
结合 toolbarBackground 修饰符自定义背景样式。

基本语法 #

// 应用于 NavigationStack 或 NavigationSplitView
NavigationStack {
    ContentView()
}
.toolbarBackground(.visible, for: .navigationBar) // 显示背景
.toolbarBackgroundVisibility(.visible) // 控制背景可见性

或动态控制：

@State private var isBackgroundVisible = true

NavigationStack {
    ContentView()
}
.toolbarBackgroundVisibility(isBackgroundVisible ? .visible : .hidden)

主要参数 #

参数值	描述
`.automatic`	系统默认行为（如 iOS 滚动时自动隐藏背景）
`.visible`	强制显示背景
`.hidden`	强制隐藏背景（透明化）

使用场景与示例 #

1. 全局隐藏工具栏背景 #

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List(0..<100) { i in
                Text("Row \(i)")
            }
            .navigationTitle("列表")
        }
        .toolbarBackground(.hidden, for: .navigationBar) // 隐藏导航栏背景
        .toolbarBackgroundVisibility(.hidden) // 确保背景不可见
    }
}

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

struct ArticleView: View {
    var body: some View {
        NavigationStack {
            ScrollView {
                // 长文本内容
            }
            .navigationTitle("文章")
        }
        .toolbarBackgroundVisibility(.automatic) // 滚动时自动隐藏背景
        .toolbarBackground(.ultraThinMaterial) // 设置背景材质
    }
}

3. 动态切换背景可见性 #

struct DynamicBackgroundView: View {
    @State private var isBackgroundHidden = false
    
    var body: some View {
        NavigationStack {
            Button("切换背景") {
                withAnimation {
                    isBackgroundHidden.toggle()
                }
            }
            .navigationTitle("动态背景")
        }
        .toolbarBackgroundVisibility(isBackgroundHidden ? .hidden : .visible)
        .toolbarBackground(.blue.gradient, for: .navigationBar)
    }
}

与 `toolbarBackground` 的配合 #

toolbarBackgroundVisibility 通常与 toolbarBackground 结合使用，前者控制是否显示背景，后者定义背景样式：

NavigationStack {
    ContentView()
}
.toolbarBackground(.red.opacity(0.5), for: .navigationBar) // 设置半透明红色背景
.toolbarBackgroundVisibility(.visible) // 显示背景

注意事项 #

作用范围
toolbarBackgroundVisibility 需应用在 导航容器（如 NavigationStack）上，影响其内部所有子视图的工具栏背景行为。
平台差异
- iOS/iPadOS：滚动时默认隐藏背景（.automatic），上滑显示。
- macOS：工具栏背景通常始终可见，除非显式设置为 .hidden。
与 toolbar 的兼容性
即使隐藏背景，通过 toolbar { ... } 添加的工具栏项依然可见（除非同时隐藏工具栏本身）。

动画支持
可通过 withAnimation 实现平滑过渡效果：

Button("切换背景") {
    withAnimation(.easeInOut) {
        isBackgroundVisible.toggle()
    }
}

完整示例：沉浸式滚动效果 #

struct ImmersiveListView: View {
    var body: some View {
        NavigationStack {
            ScrollView {
                VStack(spacing: 20) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .frame(maxWidth: .infinity)
                            .padding()
                            .background(.gray.opacity(0.1))
                            .clipShape(RoundedRectangle(cornerRadius: 8))
                    }
                }
                .padding()
            }
            .navigationTitle("沉浸式列表")
        }
        .toolbarBackground(.hidden, for: .navigationBar) // 隐藏默认背景
        .toolbarBackgroundVisibility(.automatic) // 滚动时自动隐藏
    }
}

总结 #

场景	推荐参数	说明
沉浸式滚动	`.automatic`	滚动时自动隐藏背景
始终显示自定义背景	`.visible`	搭配 `toolbarBackground` 使用
完全透明工具栏	`.hidden`	隐藏背景，仅显示工具栏项

通过 toolbarBackgroundVisibility，可以灵活控制工具栏背景的展示逻辑，提升视觉一致性或实现动态交互效果。