macOS HIG 设计师

遵循苹果人机界面指南，使用 macOS Tahoe 的液态玻璃设计系统，设计原生 macOS 应用程序。

工作流程决策树

用户请求
│
├─► 审查我的 macOS UI 代码
│ └─► 运行 HIG 合规性检查（第 11 节）
│ └─► 报告违规并提供修复方案
│
├─► 现代化此 macOS 代码
│ └─► 识别已弃用的 API
│ └─► 应用现代 API 替换（第 10 节）
│
└─► 为 macOS 构建[功能]
└─► 首先遵循 HIG 原则进行设计
└─► 使用现代 SwiftUI 模式实现

1. 设计原则（macOS Tahoe）

三大核心原则

液态玻璃理念

液态玻璃将透明度、反射、折射和流动性结合磨砂美学：

swift
// macOS Tahoe 液态玻璃效果
.glassEffect() // 主要液态玻璃材质
.glassEffect(.regular.tinted) // 着色变体（26.1+）

// Tahoe 之前的回退方案
.background(.ultraThinMaterial)
.background(.regularMaterial)
.background(.thickMaterial)

何时使用液态玻璃：

• - 侧边栏、工具栏和导航框架
• 浮动面板和弹出窗口
• Dock 和小组件背景
• 系统级 UI 元素

何时不使用：

• - 主要内容区域（文档、媒体）
• 密集数据展示（表格、多项目列表）
• 可读性至关重要的文本密集型界面

2. 导航模式

NavigationSplitView（主要模式）

适用于基于文档和内容密集型应用的三列布局：

swift
struct ContentView: View {
@State private var selection: Item.ID?
@State private var columnVisibility: NavigationSplitViewVisibility = .all

var body: some View {
NavigationSplitView(columnVisibility: $columnVisibility) {
// 侧边栏（源列表）
List(items, selection: $selection) { item in
NavigationLink(value: item) {
Label(item.title, systemImage: item.icon)
}
}
.navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 300)
} content: {
// 内容列（可选中间列）
ContentListView(selection: selection)
} detail: {
// 详情视图
DetailView(item: selectedItem)
}
}
}

侧边栏模式

swift
// 带分组的源列表
List(selection: $selection) {
Section(资料库) {
ForEach(libraryItems) { item in
Label(item.name, systemImage: item.icon)
.tag(item)
}
}

Section(收藏集) {
ForEach(collections) { collection in
Label(collection.name, systemImage: folder)
.tag(collection)
.badge(collection.count)
}
}
}
.listStyle(.sidebar)

检查器面板（尾部侧边栏）

swift
struct DocumentView: View {
@State private var showInspector = true

var body: some View {
MainContentView()
.inspector(isPresented: $showInspector) {
InspectorView()
.inspectorColumnWidth(min: 200, ideal: 250, max: 400)
}
.toolbar {
ToolbarItem {
Button {
showInspector.toggle()
} label: {
Label(检查器, systemImage: sidebar.trailing)
}
}
}
}
}

3. 窗口管理

窗口配置

swift
@main
struct MyApp: App {
var body: some Scene {
// 主文档窗口
WindowGroup {
ContentView()
}
.windowStyle(.automatic)
.windowToolbarStyle(.unified)
.defaultSize(width: 900, height: 600)
.defaultPosition(.center)

// 设置窗口
Settings {
SettingsView()
}

// 工具窗口
Window(检查器, id: inspector) {
InspectorWindow()
}
.windowStyle(.plain)
.windowResizability(.contentSize)
.defaultPosition(.topTrailing)

// 菜单栏额外项
MenuBarExtra(状态, systemImage: circle.fill) {
StatusMenu()
}
.menuBarExtraStyle(.window)
}
}

窗口样式

窗口状态恢复

swift
WindowGroup {
ContentView()
}
.handlesExternalEvents(matching: Set(arrayLiteral: main))
.commands {
CommandGroup(replacing: .newItem) {
Button(新建文档) {
// 处理新建文档
}
.keyboardShortcut(n)
}
}

基于文档的应用

swift
@main
struct DocumentApp: App {
var body: some Scene {
DocumentGroup(newDocument: MyDocument()) { file in
DocumentView(document: file.$document)
}
.commands {
CommandGroup(after: .saveItem) {
Button(导出...) { }
.keyboardShortcut(e, modifiers: [.command, .shift])
}
}
}
}

struct MyDocument: FileDocument {
static var readableContentTypes: [UTType] { [.plainText] }

init(configuration: ReadConfiguration) throws { }
func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper { }
}

4. 工具栏和菜单栏

工具栏配置

swift
.toolbar {
// 前导项（macOS 将其放置在标题之前）
ToolbarItem(placement: .navigation) {
Button(action: goBack) {
Label(返回, systemImage: chevron.left)
}
}

// 主要项（居中）
ToolbarItem(placement: .principal) {
Picker(视图模式, selection: $viewMode) {
Label(图标, systemImage: square.grid.2x2).tag(ViewMode.icons)
Label(列表, systemImage: list.bullet).tag(ViewMode.list)
}
.pickerStyle(.segmented)
}

// 尾部项
ToolbarItemGroup(placement: .primaryAction) {
Button(action: share) {
Label(分享, systemImage: square.and.arrow.up)
}

Button(action: toggleInspector) {
Label(检查器, systemImage: sidebar.trailing)
}
}
}
.toolbarRole(.editor) // 或 .browser、.automatic

自定义菜单栏

swift
.commands {
// 替换现有菜单组
CommandGroup(replacing: .newItem) {
Button(新建项目) { }
.keyboardShortcut(n)
Button(从模板新建...) { }
.keyboardShortcut(n, modifiers: [.command, .shift])
}

// 添加到现有组
CommandGroup(after: .sidebar) {
Button(切换检查器) { }
.keyboardShortcut(i, modifiers: [.command, .option])
}

// 自定义菜单
CommandMenu(画布) {
Button(放大) { }
.keyboardShortcut(+)
Button(缩小) { }
.keyboardShortcut(-)
Divider()
Button(适应窗口) { }
.keyboardShortcut(0)
}
}

菜单栏应用

swift
MenuBarExtra(应用状态, systemImage: statusIcon) {
VStack(alignment: .leading, spacing: 8) {
Text(状态: \(status))
.font(.headline)

Divider()

Button(打开主窗口) {
openWindow(id: main)
}

Button(退出) {
NSApplication.shared.terminate(nil)
}
.keyboardShortcut(q)
}
.padding()
}
.menuBarExtraStyle(.window) // 或 .menu