MenuBarExtra 是 SwiftUI 在 macOS 13（Ventura）及以上系统中新增的 API，用于创建菜单栏 App（Status Bar App），也就是“状态栏图标 + 菜单内容” 的 App。
它是 SwiftUI 对 AppKit 中 NSStatusItem 的封装，无需写 AppDelegate 和 AppKit 代码，就能快速创建菜单栏图标和下拉内容。
基本用法
@main
struct ImageSlimApp: App {
@SceneBuilder
var menuBarExtraScene: some Scene {
if #available(macOS 13.0, *) {
MenuBarExtra("我的图标", systemImage: "gearshape") {
Button("执行操作") {
print("点击了菜单项")
}
Divider()
Button("退出") {
NSApp.terminate(nil)
}
}
}
}
var body: some Scene {
menuBarExtraScene
WindowGroup {
ContentView()
}
}
}
效果：
在右上角系统菜单栏出现一个 “⚙️” 图标；
点击图标后，弹出菜单；
菜单用 SwiftUI 构建，响应事件；
无需任何 AppKit 或 NSStatusItem 的写法。
参数详解
MenuBarExtra("标题", systemImage: "gearshape") {
// 菜单栏弹出的内容（SwiftUI View）
}“标题”：鼠标悬停时显示的文字（可以省略或设置为空）。
systemImage：SF Symbols 的图标名，用作菜单栏图标。
{}：SwiftUI 构建的菜单内容（可以是 Button, Text, Toggle 等）。
功能
1、自定义图标：使用 SF Symbols 或图像资源。
2、下拉菜单（动态 View）：完全用 SwiftUI 构建。
3、可响应点击、切换、选项：像普通 View 一样响应。
4、状态持久化（可绑定 @State）：可动态更新菜单项状态。
5、无需 AppDelegate / NSStatusItem：完全 SwiftUI 化。
更多配置
1、菜单开关
@State private var isOn = false
MenuBarExtra("状态工具", systemImage: "bolt.fill") {
Toggle("启用功能", isOn: $isOn)
Button("重载配置") {
// 执行操作
}
Divider()
Button("退出") {
NSApp.terminate(nil)
}
}
当绑定Toggle控件，开启Toggle时，状态栏菜单会显示勾选状态。
2、禁用菜单
MenuBarExtra("状态工具", systemImage: "bolt.fill") {
Toggle("启用功能", isOn: $isOn)
Button("重载配置") {
// 执行操作
}
Divider()
Button("退出") {
NSApp.terminate(nil)
}
.disabled(true) // 禁用
}
3、自定义菜单图标
MenuBarExtra(content: {
Button("执行操作") {
print("点击了菜单项")
}
Divider()
Button("退出") {
NSApp.terminate(nil)
}
}, label: {
Image("templateIcon")
})
注意，图片应该使用模版图像（Template Image），用于适配浅色/深色模式。
关于模版图像的知识，可以阅读《macOS状态栏图标关键组件NSStatusItem》的注意事项部分。
MenuBarExtra vs NSStatusItem
1、macOS 支持版本：MenuBarExtra支持macOS 13+，NSStatusItem支持macOS 10.10+。
2、代码量：MenuBarExtra代码少，纯 SwiftUI，NSStatusItem相比之下多一点，可能还需要用到 AppDelegate进行状态控制。
3、自定义弹窗 UI：MenuBarExtra只能是菜单样式（列表），NSStatusItem可自定义为任意浮窗。
4、动画与行为控制：MenuBarExtra受限（系统菜单样式），NSStatusItem非常灵活。
5、适合快速开发：MenuBarExtra适合快速开发，NSStatusItem适合自定义悬浮窗口。
使用场景
使用 MenuBarExtra，适合开发：
1、小工具类 App（比如 Todo、切换器、快捷操作）
2、简单状态切换（开关 Wi-Fi、显示状态）
3、不需要复杂浮窗，只需要下拉菜单的功能
如果需要：
1、精确控制窗口位置
2、显示复杂 UI（输入框、图表）
3、像 Dropbox 一样弹出浮动小窗口
那么就该用 NSStatusItem。
总结
MenuBarExtra可以快速制作状态栏菜单，支持macOS13以上的系统。
如果需要支持macOS13以下的系统，或者自定义复杂的状态栏或状态栏浮窗，就需要使用NSStatusItem，
如果在macOS上同时启用MenuBarExtra和NSStatusItem，macOS13以上的系统显示MenuBarExtra，13以下的系统显示NSStatusItem。
相关文章
1、macOS顶部和上下文菜单NSMenu：https://fangjunyu.com/2025/06/23/macos%e9%a1%b6%e9%83%a8%e5%92%8c%e4%b8%8a%e4%b8%8b%e6%96%87%e8%8f%9c%e5%8d%95nsmenu/
2、macOS状态栏图标关键组件NSStatusItem：https://fangjunyu.com/2025/06/26/macos%e8%8f%9c%e5%8d%95%e6%a0%8f%e5%9b%be%e6%a0%87%e5%85%b3%e9%94%ae%e7%bb%84%e4%bb%b6nsstatusitem/
3、macOS单个菜单项类NSMenuItem：https://fangjunyu.com/2025/06/25/macos%e5%8d%95%e4%b8%aa%e8%8f%9c%e5%8d%95%e9%a1%b9%e7%b1%bbnsmenuitem/
4、macOS状态栏图标按钮类NSStatusBarButton：https://fangjunyu.com/2025/06/26/macos%e7%8a%b6%e6%80%81%e6%a0%8f%e5%9b%be%e6%a0%87%e6%8c%89%e9%92%ae%e7%b1%bbnsstatusbarbutton/
