Keel v0.5.1 English GitHub

native/tray

托盘图标与原生弹出菜单。仅依赖 native 和 native/internal/sys,不依赖 UI 或 Gio。应用可以与 ui/window 组合,也可以独立运行事件循环。

icon, err := tray.New(tray.Options{
    Icon: artwork, // image.Image,每个轴 1..1024 像素,编码为 PNG 快照
    Template: true,
    Tooltip: "My app",
    Menu: []tray.MenuItem{
        {ID: "open", Title: "Open", OnSelect: func() {
            core.Update(openWindow)
        }},
        {Separator: true},
        {ID: "quit", Title: "Quit", OnSelect: window.Quit},
    },
})
if err != nil { log.Fatal(err) }
window.MainWithOptions(window.MainOptions{
    KeepAlive: true,
    OnQuit: func() { icon.Close() },
})

MenuItem 支持 Children、Disabled、Checked、Separator 和 OnSelect。字符串 ID 可选,在整棵树中必须唯一。子菜单不能同时有点击回调。菜单树会复制,最多 1024 项、16 层嵌套。文字和提示不能含 NUL。程序更新不触发用户回调。SetMenu 整体替换菜单,非法更新保留原菜单;原生 ID 不复用,旧菜单事件不会触发替换后的新动作。

SetIcon、SetTooltip、SetMenu 和 Close 支持并发调用。每个托盘在 Go goroutine 中串行执行回调,不在原生事件线程或 UI frame lock 内执行。写 UI 状态仍要经过 core.Update。回调可以更新或关闭自身托盘,耗时任务另开 goroutine。Close 可重复调用,丢弃排队事件,已开始执行的回调可以结束;它只移除图标,不退出进程。

平台 后端与行为
macOS purego 调用 NSStatusBar / NSMenu。Template 标记模板图片,由系统按明暗外观着色。有菜单时点击打开菜单,没有菜单时调用 OnActivate。New 同步使用主线程,放在 window.Main 前,或不持有 frame lock 的后台 goroutine 中。更新和关闭进入主队列,返回时可能还未应用。
Windows Win32 通知图标,共享隐藏顶层 HWND 和休眠的消息循环。激活触发 OnActivate,上下文激活打开原生菜单。Explorer 的 TaskbarCreated 广播会重新添加存活图标,替换和移除时释放原生资源。
Linux 纯 Go 会话 D-Bus,SNI(KDE 与 freedesktop 命名空间)和 DBusMenu。需要运行中的 StatusNotifierHost,没有时 New 返回 native.ErrUnsupported。点击与菜单行为由 Host 决定,Watcher 重启后重新注册,不需要 X11 / Wayland 窗口句柄。
其他平台、iOS、Android、Web New 返回 native.ErrUnsupported。

Template 只影响 macOS。提示文字、图标缩放与位置由桌面控制;Windows 提示最多 127 个 UTF-16 单元。注册后的图标可能在通知溢出区,也可能被桌面隐藏。不需要权限或 cgo。

独立 macOS 应用在 main 开始时调用 runtime.LockOSThread(),在该线程创建托盘并运行 tray.Main()。Windows / Linux 的 tray.Main() 保持进程运行,后端处理原生事件。不要与 window.Main 同时运行。独立应用自己管理退出与清理;tray 不引入 UI 生命周期管理器。

运行 go run ./examples/tray,默认只有托盘,通过菜单打开窗口,关闭后再打开。-smoke 自动验证图标与菜单更新、无窗口重开和显式退出。-screenshot <path> 仅渲染配套窗口。Windows / Linux 运行验收仍需要对应桌面;macOS smoke 与跨平台编译是不同的检查。

菜单图标与动画

MenuItem.Icon 接受每个轴 1..256 像素的 image.Image;New 和 SetMenu 将图片复制为 PNG,之后修改源图不会影响已安装菜单。IconTemplate 在 macOS 上按透明度遮罩着色;Windows、Linux 使用原始像素。模板标记必须有图片,分隔线不接受图标。AppKit / Win32 保持宽高比,放入 16 逻辑像素区域;Linux 通过 DBusMenu icon-data 交给 Host 决定位置与缩放。子菜单和勾选项也支持图标;替换、移除图片时,原生图片/位图资源随菜单释放。

Options.MenuAnimation 和 SetMenuAnimation 接受 MenuAnimationSystem(零值,跟随桌面)和 MenuAnimationNone。Windows 通过 TPM_NOANIMATION 禁用之后弹出的菜单动画,不改系统全局设置。macOS / Linux 对此策略返回 native.ErrUnsupported;非法枚举返回 native.ErrInvalidArgument,保留原有配置。

CancelMenuTracking(animated) 关闭当前托盘的活动菜单。macOS 遵守动画参数,Windows 立即关闭;Linux 的菜单跟踪由 Host 管理,返回 native.ErrUnsupported。macOS 操作进入主队列,完成是异步的。Capabilities() 返回 Icons、TemplateIcons、DisableOpeningAnimation、DismissAnimation 和 CancelTracking;这些表示后端控制能力,不代表当前存在托盘 Host。

if tray.Capabilities().DisableOpeningAnimation {
    if err := icon.SetMenuAnimation(tray.MenuAnimationNone); err != nil { panic(err) }
}
if tray.Capabilities().CancelTracking {
    if err := icon.CancelMenuTracking(false); err != nil { panic(err) }
}