BAMA 原生 macOS 菜单设计指南:菜单栏顺序、标签、图标、上下文菜单与 SwiftUI 命令

原创2026-10-29 20:36:271,940 阅读

BAMA 原生 macOS 菜单设计指南:菜单栏顺序、标签、图标、上下文菜单与 SwiftUI 命令

本篇技术指南以 BAMA 仓库中的 mac-design 技能文档 menus.md 为主干,系统讲解一套 macOS 应用菜单的设计规则:菜单栏的标准顺序与各菜单职责、菜单项的动词化标签、图标的使用边界、上下文菜单与 Dock 菜单的差异,以及如何用 SwiftUI 的 .commands 把这些规则落地。读完后你可以把一份“命令地图”完整映射到菜单栏、上下文菜单和 Dock 菜单上,并用仓库自带的检查标准验证菜单是否合格。

一、核心前提:所有命令都必须存在于菜单栏

菜单设计的第一条原则不是“好看”,而是可达性。menus.md 开篇给出的判断极其明确:

应用中的每一条命令都住在菜单栏里,即使是很少用的命令——因为 Full Keyboard Access 和 Help > Search 只能从菜单栏抵达它们。

这句话决定了两条工程后果:

  1. 菜单栏是命令的单一真相来源。 上下文菜单、Dock 菜单、工具栏按钮都只是同一批命令的不同入口。menus.md 在“Context menus”一节重复强调:“Every command here also lives in the menu bar.” design-rules.md 的第 17 条把它写成了可检查的规则:“每个工具栏项与功能都要有菜单栏命令,按标准顺序排列,不适用时保持可见但禁用。”
  2. 菜单是辅助技术的入口。 macOS 的“全键盘控制”(Full Keyboard Access)与“帮助 > 搜索”都遍历菜单树,因此任何只存在于自定义按钮或右键菜单里的动作,对这两条路径而言等于不存在。

BAMA 把这条原则贯彻到了模板层:App.swift 在 Window 场景上直接挂载 .commands { SidebarCommands(); ToolbarCommands(); CommandGroup(replacing: .newItem) { ... } },让“新建条目”这个动作在菜单栏与 Command-N 快捷键上同时成立,而工具栏里的 + 按钮只是它的第二个入口(见 ContentView.swift)。

二、菜单栏顺序

2.1 标准顺序

menus.md 规定的顺序是:

App, File, Edit, Format, View, 你自己的菜单, Window, Help

其中“你自己的菜单”应跟随应用结构排列,最通用的在前。文档给出的例证是 Mail:Mailbox 在 Message 之前。

需要注意 Format 不是必选项——它出现在顺序里,但下面的职责表并未给出强制内容;真正的硬性要求是 App、Edit、View、Window、Help 的存在与顺序,以及 File 的取舍规则。

2.2 各菜单职责(完整继承并补充边界)

菜单 放什么
App About <App>(应用名 16 字符以内,不带版本号)、Settings...(Command-comma)、应用级项目、Services、Hide、Hide Others、Show All、Quit
File New <Noun>(“New Event”,绝不只写 “New”)、Open...、Open Recent(显示名称而非路径,并附 Clear Menu)、Close、用 Duplicate 而不是 Save As、Rename...、Move To...、仅在导出其他格式时用 Export As...。不处理文件的应用应当重命名或直接去掉 File 菜单
Edit Undo / Redo 且必须点出具体动作(“Undo Typing”“Redo Paste”)、Cut、Copy、Paste、Delete(绝不写 Erase 或 Clear)、Select All、Find。系统会自动补上 Dictation 与 Emoji
View Show/Hide Sidebar、Show/Hide Toolbar、Show/Hide Inspector、Enter Full Screen。即使只剩 Enter Full Screen,View 菜单也要保留
Window Minimize、Zoom、Bring All to Front,随后按字母序列出已打开的窗口。只有一个窗口时也要保留。列表里不放面板(panel)。Zoom 永不进入全屏
Help <App> Help,分隔线之后放少量条目

几个容易踩错的细节值得单独展开:

  • About 不带版本号:版本号应放在 About 面板内部,而不是菜单标题里。菜单标题变长会挤压 App 菜单整体宽度。
  • New <Noun> 而非 New:名词让命令自带宾语,用户在“帮助 > 搜索”里输入“New”之外的词(如 “Event”)也能命中。
  • Duplicate 取代 Save As:这是文档型应用与非文档型应用的分野。BAMA 的模板应用不处理文件,因此它的 File 菜单实际上是可以整块省略的——这与模板只保留 App/Edit/View/Window/Help 的做法一致。
  • Delete 而非 Erase/Clear:编辑菜单的删除必须复用系统词汇,否则用户的心智模型会与系统快捷键冲突。
  • Window 菜单里的 Zoom 不进入全屏:全屏属于 View 菜单的 Enter Full Screen。把两者混为一谈是最常见的 macOS 菜单错误之一。

2.3 让 View 菜单自动长出来

手工拼 View 菜单既容易遗漏,又会与系统行为打架。BAMA 的做法是调用框架提供的命令组:

  • SidebarCommands() → View > Show Sidebar,快捷键 Control-Command-S;
  • ToolbarCommands() → View > Show Toolbar(Option-Command-T)与 Customize Toolbar;
  • InspectorCommands() → View > Show Inspector,Control-Command-I。

依据见 toolbars.md 与 SKILL.md。这里有一条重要的不要重复约束:InspectorCommands() 已经提供了 Show Inspector 的快捷键,如果你又在工具栏按钮上写 .keyboardShortcut("i", modifiers: <a href="https://link.gitcode.com/i/ed52f7ff3975f3d671ee3cba08c59437" target="_blank">.command, .control]),就出现了两个同键命令,[patterns.md 明确要求“Use one or the other, not both.”

三、标签:动词、省略号、状态与勾选

menus.md 用四组短规则覆盖了几乎所有菜单文案决策:

  1. 动词或动词短语,Title Case,不加冠词。 例:“Add Bookmark”,而不是 “Add a Bookmark”。
  2. 需要更多输入才执行的命令加省略号。 例:“Rename...”、“Export As...”。这与 design-rules.md 第 70 条的按钮规则同源:打开另一个窗口或视图的按钮也以省略号结尾。
  3. 可切换项随状态改标签。 例:“Show Map” / “Hide Map”。当仅有名词会产生歧义时补上动词,例:“Turn Grid On”。
  4. 勾选标记表示属性已开启(如 Bold),同时提供一个能清除多项的条目(如 Plain)。

此外还有三条结构性规则:

  • 子菜单的触发条件:同一个词在超过两个条目中重复时(如 “Sort By”)。层级只有一层,约五项。即使子菜单内所有条目都不可用,子菜单本身仍保持启用——否则用户无法展开去看“为什么不能用”。
  • 不适用的条目保持可见并被禁用,而不是隐藏。这与上下文菜单的规则正好相反,是菜单栏与右键菜单最重要的差异点。
  • Option 键动态条目:只允许一个修饰键,只出现在菜单栏,且永远不能成为完成某事的唯一途径。

3.1 Undo 必须说出动作名

标签规则里最容易被忽略的是 Undo。menus.md 的 SwiftUI 一节给出做法:

undoManager?.setActionName("Add Task")   // 注册撤销之后调用

之后 Edit 菜单会自动读成 “Undo Add Task”。BAMA 在 patterns.md 中给出了配套的 SwiftData 实现要点:在窗口的 undo manager 上注册反向操作,不要设置 mainContext.undoManager = UndoManager()(独立的管理器接不到 Edit > Undo),并在注册后立即 setActionName。这与 design-rules.md 第 79 条一致:Undo 提示条不能是唯一途径,Edit > Undo、Command-Z 必须同时在。

四、图标:少而有理由

menus.md 对菜单图标给出了四条可判定规则:

  • 少而有意:只给关键动作、关键功能、地点、设备、以及视觉性概念(旋转、翻转)。
  • 一组全有或全无:同一组条目要么都给图标,要么都不给。
  • 相关条目组只给第一个加符号:例如 Copy、Copy Link、Copy as Markdown,只有 Copy 带符号。
  • 没有清晰匹配的符号就不加。标准动作要使用标准符号,符号表见 design-rules.md 第 65 条:Copy document.on.document、Paste document.on.clipboard、Duplicate plus.square.on.square、Rename pencil、Move folder、Filter line.3.horizontal.decrease、Share square.and.arrow.up、Delete trash、More ellipsis、Compose square.and.pencil、Archive archivebox。垃圾桶图标只能表示删除。

还有一个只影响 SwiftUI 的实现细节:在菜单栏命令里,条目默认不显示图标,必须显式写 .labelStyle(.titleAndIcon)(menus.md 标注来源 WWDC26-269)。这意味着你在 CommandMenu 里给 Button("Star", systemImage: "star") 写了符号名,菜单里也可能看不到它——这不是符号名写错了,而是标签样式没设。

五、上下文菜单:与菜单栏相反的世界

上下文菜单(右键菜单)的规则与菜单栏几乎是镜像关系。menus.md 的五条要求:

  • 不适用的条目隐藏(而菜单栏里是保留并禁用)。例外:Cut、Copy、Paste 可以保持灰色不可用。
  • 不显示键盘快捷键。快捷键属于菜单栏,右键菜单里出现快捷键会让人误以为该快捷键只在此处有效。
  • 约三组,最常用的在最前,最多一层子菜单。
  • 只在能增加信息时才加标题,例如 “3 Items Selected”。
  • 每条命令也必须存在于菜单栏。
  • 凡是能对某个条目执行动作的地方,都以同样方式提供上下文菜单——列表行、网格单元、画布对象应当表现一致。

BAMA 模板里的用法是最小可用形态:ContentView.swift 在列表行上挂 .contextMenu { Button("Delete", role: .destructive) { context.delete(item) } }。按上面的规则,这个 Delete 还必须同时出现在菜单栏(模板里由 Edit 菜单与 .onDeleteCommand 路径承担),并且这个右键菜单里不应写 ⌫ 之类的快捷键提示。

design-rules.md 第 68 条把这套规则总结成一句可检查的话,并给出了唯一例外:菜单栏应用的 status item 菜单就是它的菜单栏,因此可以显示用户的全局快捷键。

六、Dock 菜单:应用不在前台时的少量高价值入口

Dock 菜单服务的是“应用没有在前台”这个场景,因此只放少量高价值动作。menus.md 的例证是 Mail:Get New Mail、New Message,再加上系统自动追加的已打开窗口列表。约束是:每个条目在应用其他地方也必须存在。

实现代码(文档原文):

final class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDockMenu(_ sender: NSApplication) -> NSMenu? {
        let menu = NSMenu()
        menu.addItem(withTitle: "New Task", action: #selector(newTask), keyEquivalent: "")
        return menu
    }

    @objc private func newTask() { /* same action as File > New Task */ }
}

三个实现要点:

  1. 返回 NSMenu 而不是 SwiftUI 视图,因此 Dock 菜单天然属于 AppKit 侧,需要 NSApplicationDelegate。BAMA 的模板已经通过 @NSApplicationDelegateAdaptor(AppDelegate.self) 挂好了委托对象(App.swift),加一个方法即可。
  2. keyEquivalent: "":Dock 菜单不承载快捷键,与上下文菜单同理。
  3. 动作必须是同一个 selector / 同一段逻辑,而不是复制一份实现。注释里那句 same action as File > New Task 就是这条要求的落点。

在权限层面,Dock 菜单是“零成本”的:os-integrations/SKILL.md 的能力表把它列为 applicationDockMenu(_:) in the app delegate,权限列写的是 None。同一张表还强调了一条选择原则:“当两行解决同一个任务时,优先选不需要权限的那一行”——Dock 菜单因此优于任何需要 Accessibility 的替代方案。

七、SwiftUI:把规则写成 .commands

7.1 文档给出的完整示例

.commands {
    SidebarCommands()                 // View > Show Sidebar, Control-Command-S
    ToolbarCommands()                 // View > Show Toolbar, Customize Toolbar
    CommandGroup(replacing: .newItem) {
        Button("New Task") { model.addTask() }
            .keyboardShortcut("n")
    }
    CommandGroup(after: .sidebar) {
        // A label that follows the state.
        Button(model.showsCompleted ? "Hide Completed" : "Show Completed") {
            model.showsCompleted.toggle()
        }
        .keyboardShortcut("h", modifiers: [.command, .shift])
    }
}

这段示例同时演示了三种手法:

  • 系统命令组:SidebarCommands() 与 ToolbarCommands() 负责标准 View 菜单项,避免手工重写。
  • 替换而非追加:replacing: .newItem 把系统的 “New” 占位项换掉,从而满足 “New ” 的命名要求,而不是留下一个孤零零的 “New”。
  • 位置锚点:after: .sidebar 把自定义项插到 Sidebar 相关命令之后,保持 View 菜单的系统顺序。CommandGroup 的 before: / after: 就是文档中“菜单顺序”这一规则在代码层的表达。

7.2 系统赠送的 Window 与 Help 菜单

menus.md 明确写道:Window 或 WindowGroup 场景会从系统获得 Window 与 Help 菜单,保留它们。这解释了一个常见困惑:为什么你没有写 Window 菜单,运行时却有 Minimize / Zoom / Bring All to Front。规则是不要删除、不要重建、不要在旁边再加一份。

7.3 命令需要读取选区时

菜单命令作用于“当前聚焦窗口的选区”。patterns.md 给出了先声明 FocusedValueKey、再用 .focusedSceneValue 注入、在 Commands 里用 @FocusedValue 读取的完整链路,并用 .disabled(item == nil) 让“没有选区时禁用”成为可检查的状态:

struct ItemCommands: Commands {
    @FocusedValue(\.selectedItem) private var item

    var body: some Commands {
        CommandMenu("Item") {
            Button(item?.isStarred == true ? "Unstar" : "Star", systemImage: "star") {
                item?.isStarred.toggle()
            }
            .keyboardShortcut("s", modifiers: [.command, .shift])
            .disabled(item == nil)
        }
    }
}

注意这个例子正好同时命中两条标签规则:随状态改标签(Star / Unstar)与不适用时禁用。

7.4 一个必须知道的坑:Commands 不会观察 @Observable

这是 BAMA 从实际调试中记录下来的实现事实,见 swift-swiftui/SKILL.md:

SwiftUI 的 Commands 不观察 @Observable 模型,因此读模型的标题或 .disabled(...) 会变旧。测试中,.focusedSceneValue 的 @FocusedValue 与 Commands 内部的 @ObservedObject 都未能可靠更新:选中了一行,菜单仍然保持禁用。

可以工作的做法是:把选区镜像到一个小的 ObservableObject,在 App 中观察它,再把值传进 Commands。这样 App 的 body 重建时菜单随之重建:

@MainActor final class MenuState: ObservableObject {
    static let shared = MenuState()
    @Published private(set) var selection: Set<UUID> = []
    func update(_ s: Set<UUID>) { if selection != s { selection = s } }
}

struct MyApp: App {
    @ObservedObject private var menu = MenuState.shared
    var body: some Scene {
        Window("App", id: "main") { ContentView() }
            .commands { AppCommands(model: model, selectedIDs: menu.selection) }
    }
}

同一节还有两条硬性约束,直接影响菜单快捷键设计:

  • 菜单快捷键在文本框获得焦点时也会触发。 因此绝不能用 Delete、Command-Delete、方向键、Return 作为菜单快捷键,这些键要在列表上用 .onDeleteCommand 和 .onKeyPress 处理。
  • 绝不发布“一直启用但什么也不做”的条目,要修聚焦值的数据通路。这条与 design-rules.md 第 46 条完全对应。

7.5 快捷键表

design-rules.md 第 69 条给出了标准键集合,写菜单快捷键时应逐条对照:

快捷键 含义
Command-C / V / X / Z / W / Q / N / , 复制、粘贴、剪切、撤销、关闭、退出、新建、设置,含义不可挪用
Option-Command-F 跳转到搜索框
Command-Period 取消当前操作或关闭警告框
Escape 关闭
Shift-Command-Z 只能是 Redo

禁止项同样明确:不要给已有快捷键叠加修饰键去表示一个不相关的命令;避免在标点键上使用 Option 或 Shift,因为其他键盘布局下它们位置会变。

八、菜单栏应用(LSUIElement)的特殊规则

BAMA 的规格库里有大量菜单栏工具(如 menu-bar-stats.md、clipboard-history.md、launcher.md),它们都声明 LSUIElement、无 Dock 图标。menus.md 为这类应用单列了一段规则:

  • 主菜单只在某个窗口打开时才存在。 因为 LSUIElement 应用没有常驻的菜单栏(激活策略不是 .regular),窗口关闭后菜单栏归零。
  • status item 的菜单承担菜单栏的职责,并且可以显示用户的全局快捷键(这是“上下文菜单不显示快捷键”规则的唯一例外)。
  • 主菜单至少要包含 App(带 Settings...)、Edit、Window、Help。

这条“至少四项”的要求容易被误读为“菜单栏应用不需要菜单”。实际上它约束的是状态切换的瞬间:一旦应用切换到 .regular 并打开窗口,菜单必须立即合格。design-rules.md 第 79 条补充了同源的细节:菜单栏应用的 Edit > Undo 只在它以窗口打开并切换为 .regular 时才存在。

在实现路径上,BAMA 给出两种方案:

场景 API 参考
菜单形式足够 MenuBarExtra + SF Symbol 模板图标 patterns.md
需要自定义点击行为、浮层、固定宽度文本 NSStatusItem + NSPopover menu-bar-stats.md

patterns.md 还给出两条菜单语义约束:让用户能在 Settings 里用 isInserted: 关掉菜单栏图标;永远不要让某个功能只能通过菜单栏抵达——“应用也有 Dock 菜单”(指向本篇第六节)。这与 menus.md 的 Dock 菜单段落形成闭环:菜单栏、Dock 菜单、主窗口三处提供同一批动作。

九、把菜单做对的三层验证

BAMA 的验证思路是“内层查数据、外层查真实菜单”,见 test-mac-app/SKILL.md。

9.1 自检里按键并遍历菜单树

NSApp.mainMenu?.performKeyEquivalent(with: commandK)  // 触发一个菜单快捷键

遍历 NSApp.mainMenu,把每个命令的标题、key equivalent、修饰键、符号与你的“命令地图”比对。一次循环就能把“每个动作都有菜单项和快捷键”变成逐项检查。app-brief 定义的 brief 中本来就有 Command map(每条动作、它所在的菜单、它的快捷键),这正是比对的基准。

另一条相关检查项:每个动作在 Shortcuts 里的标题要等于它的菜单标题,否则同一个动作在系统“快捷键”设置里会出现另一个名字。

9.2 不要在应用内部测试 SwiftUI 菜单状态

文档明确劝退这条路,理由是三条具体的失败原因:SwiftUI 菜单项不带 action selector、isEnabled 按 SwiftUI 自己的节奏更新、以及当另一个应用在前台时检查必然失败(而 agent 工作时几乎总是这种情况)。替代方案:

  • 自检里检查 命令收到了什么(传进去的选区),并直接执行菜单项所调用的动作;
  • 真实菜单用 Accessibility 从外部检查:先在种子数据副本上确认“未选中时 To-Do > Complete 为禁用”,再点击一行后确认“执行后该行完成且选中下一行”。

9.3 快照与视觉复核

SKILL.md 的 Review set 要求把菜单栏菜单本身纳入明暗两套快照。检查项包括:焦点环、被选中的文本、无用滚动条、短内容下方的空带,以及窗口是否作为 key window 截取——非活动窗口的截图(灰色红绿灯、变暗的开关)或玻璃效果被压平的截图不算完成复核。

十、完工判据

menus.md 结尾给出了一行可判定的验收条件,逐字对应上面的每一节:

当菜单栏遵循上述顺序、每个工具栏与上下文菜单命令都有对应的菜单栏条目,且除 Cut、Copy、Paste 之外没有任何上下文菜单显示快捷键或禁用项时,即告完成。

落实到日常开发,可以把这句话拆成一份提交前清单:

  1. 菜单栏顺序为 App、File、Edit、Format、View、自定义、Window、Help;无文件的应用已去掉 File。
  2. New 后面带名词;会请求更多输入的命令带省略号;可切换项随状态改标签。
  3. Undo 显示具体动作名(setActionName),且 Edit > Undo 与 Command-Z 始终可达。
  4. 图标:同组全有或全无;相关组只给第一个;无清晰符号就不加;SwiftUI 命令里记得 .labelStyle(.titleAndIcon)。
  5. 上下文菜单:隐藏不适用项、不显示快捷键、约三组、至多一层子菜单、每条命令都能在菜单栏找到。
  6. Dock 菜单:少量高价值项、keyEquivalent: ""、与菜单栏共用同一实现。
  7. View 菜单由 SidebarCommands() / ToolbarCommands() / InspectorCommands() 生成,且没有重复快捷键。
  8. 菜单状态随选区刷新(MenuState 镜像),不存在“永远启用却无动作”的条目。
  9. 没有把 Delete、Command-Delete、方向键、Return 当作菜单快捷键。
  10. 菜单栏应用(LSUIElement)保留 App(含 Settings...)、Edit、Window、Help,且功能不只通过菜单栏可达。

十一、继续阅读的仓库入口

登录后查看全文
bama