macOS 窗口与工具栏样式参考适用于 macOS SwiftUI 应用的窗口配置、工具栏样式、尺寸、定位和导航模式。目录快速查找表工具栏样式窗口样式窗口尺寸MenuBarExtra 样式macOS 专属导航布局macOS 行为命令与键盘最佳实践快速查找表API可用性仅 macOS用途windowToolbarStyle(_:)macOS 11.0是设置工具栏样式.unified、.unifiedCompact、.expandedwindowStyle(_:)macOS 11.0否支持.hiddenTitleBar实现无边框窗口windowResizability(_:)macOS 13.0否控制调整大小手柄和绿色缩放按钮的行为defaultSize(width:height:)macOS 13.0否用户创建新窗口时的初始 frame 尺寸defaultPosition(_:)macOS 13.0否窗口在屏幕上的初始位置windowIdealPlacement(_:)macOS 15.0否带显示几何信息的闭包用于精确定位窗口menuBarExtraStyle(_:)macOS 13.0是将 MenuBarExtra 设置为.menu或.window样式NavigationSplitViewmacOS 13.0否在 macOS 上列始终并排可见侧边栏半透明InspectormacOS 14.0否尾缘侧边栏面板可通过拖动调整大小工具栏样式windowToolbarStylemacOS 专属控制工具栏和标题栏的显示方式。应用于场景。mainstructMyApp:App{varbody:someScene{WindowGroup{ContentView()}// 标题栏和工具栏在同一行.windowToolbarStyle(.unified)}}可用样式样式描述.automatic系统默认.unified标题栏和工具栏合并为一行.unifiedCompact与 unified 相同但垂直高度更小.expanded标题栏显示在工具栏上方更多工具栏空间// Unified compact — 最小化边框.windowToolbarStyle(.unifiedCompact)// Expanded — 标题栏在工具栏上方.windowToolbarStyle(.expanded)// Unified 且隐藏标题.windowToolbarStyle(.unified(showsTitle:false))工具栏内容structContentView:View{StateprivatevarsearchTextvarbody:someView{NavigationSplitView{SidebarView()}detail:{DetailView()}.toolbar{ToolbarItem(placement:.automatic){Button(action:addItem){Label(Add,systemImage:plus)}}}.searchable(text:$searchText,placement:.sidebar)}}窗口样式windowStyle设置窗口的视觉样式。对无边框、沉浸式窗口使用.hiddenTitleBar。// 标准标题栏默认WindowGroup{ContentView()}.windowStyle(.titleBar)// 隐藏标题栏 — 无边框窗口WindowGroup{ContentView()}.windowStyle(.hiddenTitleBar)使用场景.hiddenTitleBar对媒体播放器、自定义边框应用或不需要标准标题栏的沉浸式体验很有用。窗口尺寸windowResizability、defaultSize、defaultPosition这些修饰符协同配置窗口尺寸和位置WindowGroup{ContentView().frame(minWidth:600,minHeight:400)}.defaultSize(width:900,height:600).defaultPosition(.center).windowResizability(.contentMinSize)windowResizability选项值行为.automatic系统决定调整大小行为.contentSize固定为内容尺寸用户不可调整大小缩放按钮禁用.contentMinSize可调整大小最小值基于内容的minWidth/minHeightdefaultPosition选项.center、.topLeading、.top、.topTrailing、.leading、.trailing、.bottomLeading、.bottom、.bottomTrailing指南通过内容上的.frame()设置minWidth/minHeight用.contentMinSize强制执行使用.defaultSize()设置初始尺寸大于最小值defaultSize也接受CGSizewindowIdealPlacementmacOS 15.0如需精确的编程式定位使用带显示几何信息的闭包.windowIdealPlacement{contextinletscreencontext.defaultDisplay.visibleAreareturnWindowPlacement(x:screen.midX,y:screen.midY,width:screen.width/2,height:screen.height)}MenuBarExtra 样式macOS 专属在MenuBarExtra的下拉菜单和弹出面板之间选择。// 下拉菜单默认MenuBarExtra(Status,systemImage:chart.bar){Button(Action){/* ... */}}.menuBarExtraStyle(.menu)// 带自定义 SwiftUI 内容的弹出面板MenuBarExtra(Status,systemImage:chart.bar){DashboardView()}.menuBarExtraStyle(.window)导航布局macOS 行为NavigationSplitView在 macOS 上NavigationSplitView并排显示列从不错叠。侧边栏获得半透明材质背景。列支持用户调整可变宽度。NavigationSplitView{List(items,selection:$selectedId){iteminText(item.name)}.navigationSplitViewColumnWidth(min:180,ideal:220,max:300)}detail:{DetailView(id:selectedId)}.navigationSplitViewStyle(.balanced)对主-从-从布局使用三列变体sidebar/content/detail。使用.navigationSplitViewColumnWidth(min:ideal:max:)自定义列宽。InspectormacOS 14.0用于补充信息的尾缘面板。在 macOS 上它显示为侧边栏式面板可以通过拖动其边缘调整大小。structContentView:View{StateprivatevarshowInspectorfalsevarbody:someView{MainContent().inspector(isPresented:$showInspector){InspectorView().inspectorColumnWidth(min:200,ideal:250,max:400)}.toolbar{ToolbarItem{Button{showInspector.toggle()}label:{Label(Inspector,systemImage:info.circle)}}}}}命令与键盘Commands、CommandGroup、CommandMenu定义菜单栏命令。在 macOS 上这些直接填充菜单栏。在 iOS 上它们创建按键命令。.commands{CommandMenu(Tools){Button(Run Analysis){/* ... */}.keyboardShortcut(r,modifiers:[.command,.shift])}CommandGroup(after:.newItem){Button(New From Template...){/* ... */}}}CommandGroup位置选项.replacing(_:)替换系统组.before(_:)/.after(_:)插入到其旁边。常见位置.newItem、.saveItem、.help、.toolbar、.sidebar。KeyboardShortcut在 macOS 上快捷键显示在菜单项旁边并显示在悬停时的按钮提示中。Button(Save){save()}.keyboardShortcut(s,modifiers:.command)Button(Delete){delete()}.keyboardShortcut(.delete,modifiers:.command)openWindow以编程方式打开窗口。如果目标窗口已打开则将其前置。structToolbarActions:View{Environment(\.openWindow)privatevaropenWindowvarbody:someView{Button(Connection Doctor){openWindow(id:connection-doctor)}Button(Show Message){openWindow(value:message.id)// 与 WindowGroup 类型匹配}}}最佳实践大多数应用使用.unified或.unifiedCompact—— 只有需要大量工具栏项时才用.expanded在内容上设置最小 frame 尺寸并使用.windowResizability(.contentMinSize)强制执行始终提供defaultSize让新窗口以合理的尺寸启动侧边栏导航使用NavigationSplitView—— 而不是HSplitView补充面板使用Inspector—— 它自动与工具栏集成为所有可重复动作定义Commands—— macOS 用户期望键盘快捷键用#if os(macOS)包裹 macOS 专属的窗口配置用于多平台项目