Menu Bar Extra (Status Item) 菜单栏附加项 Menu Bar Extra（状态项 Status Item） macos
The icon that lives on the right side of the macOS menu bar
住在 macOS 菜单栏右侧的那个图标
标本可交互 —— 点点看。Specimen is live — try it.
Anatomy — every part, named解剖 —— 每个部件的名字
-
1 Template icon模板图标（Template Icon）
NSImage.isTemplate“The monochrome icon that recolors itself” is a template icon.
「会自己变色的单色图标」就是模板图标。
Prompt fragmentPrompt 片段an NSImage.isTemplate menu bar icon that macOS recolors automatically against light and dark menu bars
一个 NSImage.isTemplate 菜单栏图标，macOS 会自动适配浅色/深色菜单栏重新着色
-
2 Highlighted state高亮状态
NSStatusBarButton.isHighlighted“The thing behind the menu bar icon that gets highlighted” is the status button's highlighted state.
「菜单栏图标背后那个会变亮的东西」就是状态按钮的高亮状态。
Prompt fragmentPrompt 片段the NSStatusBarButton.isHighlighted state: the pale rounded background behind the menu bar icon for as long as its surface is open
NSStatusBarButton.isHighlighted 状态：菜单栏图标背后的浅色圆角底，在其界面打开期间一直显示
-
3 Attached menu or popover附着的菜单或弹出窗口
NSStatusItem.menu“The actual menu bar window that opens” is the status item's attached menu or popover.
「真正弹出来的那个菜单栏窗口」就是状态项附着的菜单或弹出窗口。
Prompt fragmentPrompt 片段the NSStatusItem.menu or attached NSPopover opened directly beneath the status item
NSStatusItem.menu 或附着的 NSPopover，在状态项正下方打开
Prompt — paste into your agentPrompt —— 直接粘贴给你的代理
Add a menu bar extra — an NSStatusItem in the macOS menu bar (SwiftUI: MenuBarExtra). While its menu or popover is open, the status item's button must show its highlighted state: the pale rounded background (NSStatusBarButton.isHighlighted), exactly like system menu bar icons.
加一个菜单栏附加项——macOS 菜单栏里的 NSStatusItem（SwiftUI 用 MenuBarExtra）。它的菜单或弹出窗口打开期间，状态项的按钮必须显示高亮状态：浅色圆角底（NSStatusBarButton.isHighlighted），和系统菜单栏图标一模一样。
Debug prompt — when it misbehaves调试 Prompt —— 当它不听话时
Debug my macOS menu bar extra (NSStatusItem, SwiftUI MenuBarExtra). Rule out: the status item deallocating because nothing retains it; the icon ignoring dark menu bars because the image is not marked template; the item silently hidden when the menu bar runs out of room; the button highlight sticking because isHighlighted is managed manually; MenuBarExtra window style behaving differently from menu style. The symptom:
调试我的 macOS 菜单栏附加项（NSStatusItem、SwiftUI MenuBarExtra）。排查：状态项被释放，因为没有对象持有它；图标在深色菜单栏下不变色，因为图像没标记为 template；菜单栏空间不够时状态项被悄悄隐藏；手动管理 isHighlighted 导致按钮高亮卡住不消失；MenuBarExtra 的 window 样式和 menu 样式行为不一致。症状：
In code代码里叫什么
| Framework框架 | Symbol符号 | Note说明 |
|---|---|---|
| AppKit | NSStatusItem | |
| SwiftUI | MenuBarExtra | macOS 13+macOS 13+ |
| AppKit | NSStatusBar.system.statusItem(withLength:) | how one is created创建它的方法 |
| AppKit | NSStatusBarButton.isHighlighted | the pale rounded background while its menu is open菜单打开期间图标背后的浅色圆角底 |