macOS SwiftUI 窗口内容顶格：我踩过的 toolbar 坑与三种解法

一个 WeChat 风桌面客户端，被顶部那条“若有若无”的灰色条带卡了三个版本。

一、问题：内容为什么顶不到窗口最上面？

用 SwiftUI 写 macOS App，想让窗口像 WeChat、飞书那样“内容从最顶上开始”，很多人的第一反应是：

WindowGroup {
    ContentView()
}
.windowStyle(.hiddenTitleBar)
.windowToolbarStyle(.unified)

再在 ContentView 上挂一组 .toolbar { ... }。

跑起来会发现：标题栏确实没了，但窗口顶部仍然留着一条带状区域，右侧内容被整体往下压，背景还是一条灰。看起来“工具条没了”，实际上只是换了个样式。

原因很简单：windowStyle 和 windowToolbarStyle 只能改变外观，只要存在 .toolbar，macOS 就会为它保留区域。你以为的“隐藏”，只是把标题文字隐藏了。

二、先理解两个容易混淆的 API

1. `fullSizeContentView` 不等于“内容顶格”

真正让内容铺满窗口的是 AppKit 层：

window.titleVisibility = .hidden
window.titlebarAppearsTransparent = true
window.titlebarSeparatorStyle = .none
window.styleMask.insert(.fullSizeContentView)

fullSizeContentView 只是允许内容视图铺到标题栏下面，SwiftUI 仍然会按 safe area 把内容往下推。所以你会看到“背景铺满了，内容还在下面”的怪异状态。

2. 必须显式忽略顶部安全区

补齐这行代码，内容才真正到达窗口上沿：

.ignoresSafeArea(.container, edges: .top)

注意是 .container 而不是 .all，避免把左右或底部也一起破坏掉。

三、三种方案，逐个看效果

方案一：系统 toolbar（不推荐）

.windowStyle(.hiddenTitleBar)
.windowToolbarStyle(.unified)

.toolbar {
    ToolbarItem(placement: .navigation) { ... }
    ToolbarItemGroup(placement: .primaryAction) { ... }
}

结果：顶部固定存在一条 toolbar 带，内容被压下去；背景色与内容不一致时，会非常明显。

结论：只要你还想“顶格”，就不要用系统 toolbar。

方案二：内容里自绘一条 40pt 顶栏

去掉 .toolbar，在右侧内容顶部加一行 40pt 的自绘 header，把按钮放进去：

VStack(spacing: 0) {
    detailTopBar
    detailContent
}

结果：系统条带消失了，内容也铺到了顶部，但右侧始终多一条 40pt 的“自绘工具条”。视觉上比方案一自然，可离“顶格”还差一步。

结论：适合确实需要一个全局操作栏的场景；如果页面本身有标题区，就会显得冗余。

方案三：彻底去掉顶栏，控件就近安置（当前方案）

最终我选择了最“干净”的做法：右侧不再有任何全局顶栏，页面自身的头部就是窗口顶部。

根视图结构：

var body: some View {
    HStack(spacing: 0) {
        if isSidebarCollapsed { collapsedSidebar } else { sidebar }
        if selectedNav == "Inbox" { inboxList }
        detailContent
    }
    .background(DealPalette.frame.ignoresSafeArea())
    .ignoresSafeArea(.container, edges: .top)
}

原来顶栏上的控件全部就近迁移：

原顶栏元素	新位置
面包屑	删除（页面标题已表意）
侧栏折叠时的搜索框	删除（默认状态下本就没有此入口）
折叠 / 展开按钮	折叠在侧栏标题行，展开在 72pt 窄栏
通知、Q4 徽标	Deals 页目标卡片上方
New deal	Deals 大标题右侧

四、三个必须处理的细节

细节 1：红绿灯会压住内容

内容铺满后，左上角红绿灯（大约 x: 12–66, y: 14–26）会直接压在侧边栏上：

侧栏展开：顶部标题行加 padding(.top, 30)，让 Logo 落到红绿灯下方；
侧栏收起：左侧保留一条 72pt 窄栏，刚好覆盖红绿灯的横向范围，展开按钮放在 padding(.top, 30) 处。

private var collapsedSidebar: some View {
    VStack(spacing: 0) {
        Button {
            withAnimation(.easeInOut(duration: 0.2)) { isSidebarCollapsed = false }
        } label: {
            Image(systemName: "sidebar.right")
                .font(.system(size: 12))
                .foregroundStyle(.secondary)
                .frame(width: 28, height: 28)
                .contentShape(Rectangle())
        }
        .buttonStyle(.plain)
        .padding(.leading, 12)
        .padding(.top, 30)
        .frame(maxWidth: .infinity, alignment: .leading)
        Spacer(minLength: 0)
    }
    .frame(width: 72)
    .overlay(alignment: .trailing) { Divider() }
}

细节 2：背景也要一起顶格

只让内容 ignore safe area、背景不 ignore，顶部就会露出根视图的底色，看起来仍然像“一条工具条”。所以每一列的背景都要单独延伸：

.background { Color(red: 0.91, green: 0.93, blue: 0.96).ignoresSafeArea(edges: .top) }

细节 3：标题栏没了，窗口还要能拖

内容盖住标题栏后，系统没有可拖拽的区域了，补一个属性即可：

window.isMovableByWindowBackground = true

按钮、输入框等控件不受影响，按住空白背景就能拖动窗口。

五、踩坑清单

有 .toolbar 就一定有条带，windowToolbarStyle 只改样式；
fullSizeContentView 只负责“能铺上去”，不负责“内容真的上去”，必须配合 ignoresSafeArea；
内容顶格后记得 isMovableByWindowBackground，否则窗口拖不动；
红绿灯必须让位：要么顶部下移 ≥ 30pt，要么左侧让出 ≥ 72pt；
背景要一起 ignore safe area，否则顶部露底；
页面自身的 padding(.top, …) 别和红绿灯留白重复叠加，否则首屏空得莫名其妙。

六、如果以后还想要顶栏

优先用 .safeAreaInset(edge: .top) 自绘，而不是系统 .toolbar，高度和背景都可控；
或者用 overlay(alignment: .top) 做悬浮层，但要给页面头部预留 padding，避免遮挡；
真要用系统 toolbar，就接受那条区域，把 toolbar 背景调成和内容一致，至少“看起来”没有断档。

结语

“内容顶格”看起来是个布局问题，本质上是窗口装饰层与 SwiftUI 安全区之间的博弈。理清 .toolbar、fullSizeContentView、ignoresSafeArea 三者的职责，再顺手处理红绿灯和窗口拖动，就能得到和原生客户端一致的干净观感。

代码在 Prism 项目里，欢迎交流你踩过的 macOS SwiftUI 布局坑。