系统托盘

最小示例

from uda import Uda

with Uda() as uda:
    menu = uda.create_tray_menu()
    menu.add_text("设置", lambda: print("打开设置"))
    menu.add_separator()
    menu.add_text("退出", lambda: raise SystemExit(0))

    icon = uda.create_tray_icon("我的应用", tooltip="我的应用正在运行")
    icon.menu = menu

    icon.wait()          # 阻塞直到 stop() 或 destroy()

Node.js 侧：

const { Uda } = require('./uda');

const uda = new Uda();
const menu = uda.createTrayMenu();
menu.addText('设置', () => console.log('打开设置'));
menu.addSeparator();

const icon = uda.createTrayIcon('我的应用', { tooltip: '我的应用正在运行' });
icon.menu = menu;
await icon.wait();
icon.destroy();

菜单模型

跨平台统一，两侧能力一致：

行类型	Python	Node.js
文本项	`menu.add_text(label, callback)`	`menu.addText(label, callback)`
复选框	`menu.add_checkbox(label, checked, callback)`	`menu.addCheckbox(label, checked, callback)`
分隔线	`menu.add_separator()`	`menu.addSeparator()`

回调签名：

文本项：callback()
复选框：callback(checked: bool)，其中 checked 是点击后的新状态

平台实现

平台	协议
Linux	`org.kde.StatusNotifierItem`（SNI）+ `com.canonical.dbusmenu`
Windows	`Shell_NotifyIconW`（`NOTIFYICON_VERSION_4`）+ 自建弹出菜单

图标：传路径即可

icon.icon = "icons/UniDesktop_3D_transparent_mini.png"

SDK 内部会解码 PNG（含逐行反滤波、调色板展开、非 8 位深扩展）、按目标尺寸降采样、按需做通道对齐，然后经 uda_tray_set_icon_rgba 提交像素。

线程模型

生命周期：stop / wait / destroy

方法	作用
`icon.wait()`	阻塞当前线程，直到 `stop()` 或 `destroy()` 被调用
`icon.stop()`	让 `wait()` 返回，但不注销图标（图标仍在托盘）
`icon.destroy()`	从托盘注销并销毁句柄，`wait()` 随之返回

典型模式：

icon = uda.create_tray_icon("我的应用")
try:
    icon.wait()
finally:
    icon.destroy()

配合菜单项退出：

def quit():
    icon.stop()      # 让 wait() 返回，finally 里再 destroy

menu.add_text("退出", quit)
icon.menu = menu
icon.wait()
icon.destroy()

显示与隐藏

icon.visible = False     # 隐藏但不注销
icon.visible = True      # 恢复

清理

TrayIcon 与 TrayMenu 都实现了 Drop / Symbol.dispose，退出 with 块时自动注销；忘记释放时 __del__ / dispose 会兜底。Uda.release_all() 可一次性释放本对象持有的全部托盘资源与常亮锁。