用途:为每个 SwiftUI 窗口按其职责定制外观与行为,先确定窗口所属场景(Window、WindowGroup 或专用工具场景),再调整工具栏/标题区、背景材质、缩放与恢复行为、初始或缩放位置。优先使用 SwiftUI 提供的场景与窗口修饰符,而非临时 AppKit 桥接。
主要能力:工具栏与标题方面,可用 .toolbar(removing: .title) 隐藏可见标题但保留逻辑标题,用 .toolbarBackgroundVisibility(.hidden, for: .windowToolbar) 让内容延伸至顶部,或用 .toolbarVisibility(.hidden, for: .windowToolbar) 完全隐藏工具栏。拖拽区域方面,隐藏工具栏背景或移除工具栏后,用 WindowDragGesture() 扩展可拖拽区域,并配合 .allowsWindowActivationEvents(true)。背景材质可用 .containerBackground(.thickMaterial, for: .window)。窗口行为可用 .windowMinimizeBehavior(.disabled)、.restorationBehavior(.disabled)、.defaultLaunchBehavior(.presented)。位置可用 .defaultWindowPlacement 与 .windowIdealPlacement,配合 content.sizeThatFits(.unspecified) 和 context.defaultDisplay.visibleRect。无边框窗口可用 .windowStyle(.plain)。
使用方式:按工作流检查场景声明并分类窗口角色,调整工具栏与标题呈现,确保仍有可用拖拽区域,细化最小化、恢复、缩放与启动行为,设置默认与理想位置,再用 build-run-debug 在真实 .app 中验证。若 SwiftUI 修饰符不足,改用 appkit-interop 做窄范围 NSWindow 桥接。
适用场景:主浏览窗口、检查器/详情工具窗口、关于/支持窗口、媒体播放窗口、欢迎窗口及无边框自定义界面。
限制:这些 API 为 macOS 15+ SwiftUI 窗口/场景定制,旧部署目标需更多 AppKit 桥接或可用性判断。不要仅为隐藏忘记设置的标题而移除标题;隐藏工具栏背景或整个工具栏时必须补回拖拽能力;不要在主文档/导航窗口随意禁用恢复;不要硬编码单一显示器尺寸;不要留下无拖拽或关闭路径的无边框窗口。具体修饰符示例见 references/api-snippets.md。