如何用 tinyjs 打造系统托盘应用?菜单栏常驻、全局快捷键与窗口隐藏完全攻略

原创2026-10-16 13:02:091,958 阅读

如何用 tinyjs 打造系统托盘应用?菜单栏常驻、全局快捷键与窗口隐藏完全攻略

tinyjs 是一个用纯 JavaScript 构建原生桌面应用的轻量框架(约 6MB,无 Electron、无 Node、无打包的浏览器内核),它对系统托盘应用提供了开箱即用的支持:菜单栏常驻图标、原生右键菜单、全局快捷键唤出窗口、关闭窗口只隐藏不退出,甚至"零窗口"的纯托盘 Agent 模式都内置好了。本文将带你从零完成一个菜单栏常驻应用的完整思路与关键配置。

tinyjs 系统托盘应用示例:桌面音乐播放器 amp 的多窗口界面

为什么选择 tinyjs 做托盘应用?

传统做法是用 Electron 做一个"菜单栏小工具",结果安装包动辄 100MB 起步。tinyjs 的思路完全不同:

  • 体积约 6MB:后端是 txiki.js 运行时,前端用系统自带的 WebView(macOS 用 WebKit、Windows 用 WebView2、Linux 用 WebKitGTK)渲染普通 HTML/CSS/JS;
  • 前后端走本地私有 socket 通信,不占任何 HTTP 端口;
  • 托盘、菜单、通知、剪贴板、全局快捷键全部是原生 API,前端一行代码调用,无需自己写 FFI;
  • 关闭最后一个窗口不会杀死后端进程——这正是托盘应用最核心的行为,tinyjs 直接把它做成了 API。

安装只需一行命令(官方脚本自动识别操作系统):

curl -fsSL https://tinyjs.app/install | sh

Linux 还需要系统 WebKitGTK 运行库(如 sudo apt install libwebkit2gtk-4.1-0),Windows 需要预装的 WebView2 运行时。

三步搭好你的第一个托盘应用

先创建项目并运行:

tinyjs new mytray
cd mytray
tinyjs dev

tinyjs dev 会打开一个原生窗口并开启热重载:改前端页面即时刷新,改后端代码自动重启进程。整个项目结构很简单:

  • tinyjs.json —— 应用清单(名称、图标、托盘相关开关)
  • src/backend/main.js —— 后端,拥有完整系统权限(文件、进程、SQLite、FFI)
  • src/frontend/ —— 普通网页文件

托盘应用的灵魂在 tinyjs.json 里,只有两个关键开关:

{
  "name": "mytray",
  "title": "My Tray App",
  "activation": "accessory"
}

"activation": "accessory" 表示应用以菜单栏 Agent 身份启动:没有 Dock 图标、窗口默认隐藏、启动时连一闪而过都没有(打包后对应系统的 LSUIElement 行为)。

菜单栏常驻:一行代码挂上托盘图标

后端 src/backend/main.js 中,在 init(app) 里调用 tray.set 即可把图标挂进系统菜单栏:

export function init(app) {
  app.tray.set({
    icon: 'sf:cup.and.saucer.fill',   // 图标,也可以是 png 路径
    tooltip: '我的托盘应用',
    menu: [
      { id: 'show', label: '显示窗口' },
      { separator: true },
      { id: 'quit', label: '退出' },
    ],
  });
}

export function onTray(id, app) {
  if (id === 'show') app.window('main').show();
  if (id === 'quit') app.quit();
}

几个实用细节:

  • 图标怎么来:macOS 支持 SF Symbol('sf:名称')和文本标题;Windows 支持 'emoji:<符号>'(渲染为单色剪影);三平台通用 png 路径(默认按模板图处理,自动适配深浅色菜单);
  • 左键直接切换窗口:给 tray.set 加 primaryAction: true,左键点击触发 tray.onClick,右键(或 Ctrl 点击)才弹菜单——这是 Caffeine 风格的经典交互;
  • 菜单项支持 checked / enabled / 子菜单,和主菜单栏共用同一套形状,还能用 menu.update 局部打补丁,不用整表重设;
  • 下拉面板定位:await tiny.tray.position() 返回图标矩形,可以把弹出窗口精确锚在图标正下方(Linux 上返回 null,需改为居中显示)。

更多可直接抄的托盘应用模板见 skill/references/recipes.md。

窗口隐藏:关掉窗口但应用不死

托盘应用的核心体验是"点关闭按钮只是收进菜单栏,而不是退出"。tinyjs 用一个开关实现:

app.window('main').setHideOnClose(true);   // 前端: tiny.win.setHideOnClose(true)

配合上面的 activation: accessory,完整生命周期就是:

  1. 启动 → 菜单栏出现图标,窗口隐藏;
  2. 点击托盘"显示窗口" → app.window('main').show();
  3. 用户点关闭按钮 → 窗口隐藏,后端和托盘图标原样保留;
  4. 只有 app.quit() 或托盘菜单里的"退出"才真正结束进程。

如果不想用 accessory,也可以在运行时用 app.presence('menubar') 摘掉 Dock 图标,再 app.presence('normal') 恢复普通应用形态。

全局快捷键:任何界面都能唤出应用

想让 Cmd+Shift+K 这样的组合键在全系统范围内唤出窗口?前端页面里两行搞定:

tiny.hotkey.register('boss', 'cmd+shift+k');
tiny.hotkey.on((id) => { if (id === 'boss') tiny.win.show(); });
// 不再需要时: tiny.hotkey.unregister('boss');

后端则导出 onHotkey(id, app) 处理。组合键里 cmd 在 Windows/Linux 上自动对应 Ctrl。平台差异要注意:

平台 全局快捷键实现 注意点
macOS 系统级热键 开箱即用
Linux/X11 XGrabKey 开箱即用
Linux/Wayland GlobalShortcuts 门户 需要用户一次性批准

tiny.win.show({ activate: false }) 还能在不抢焦点的情况下显示窗口,适合做 HUD/悬浮面板。

极致轻量:无窗口托盘 Agent(Windowless Tray)

上面的方案里主窗口依然存在,只是被藏起来了。如果你的应用平时根本没有窗口——比如菜单栏时钟、剪贴板管理器、下载监控——可以用 "mainWindow": false 让后端和启动器直接"无头"运行:

{ "mainWindow": false, "activation": "accessory" }

收益非常实在——WebKit 进程直到第一次 openWindow 才启动,空闲内存占用大幅下降:

  • macOS:约 65 MiB → 约 17 MiB
  • Linux:约 330 MiB → 约 110 MiB
  • Windows:约 110 MiB → 约 12 MiB

项目里就有一个可运行的完整示例 test/windowless-tray/tinyjs.json,它的后端 test/windowless-tray/src/main.js 演示了标准生命周期:

  1. 启动时 app.windows() 为空,只有托盘图标在运行;
  2. 点菜单"Open editor" → app.openWindow('editor', { page: 'editor.html' }) 按需创建窗口;
  3. 关掉该窗口后,后端和托盘继续存活,可以再次打开;
  4. 点"Quit" → app.quit() 真正退出。

这种模式不需要 index.html,甚至不需要 src/frontend/ 目录,tinyjs build 就能打包。官方菜单栏时钟 World Clock 就是典型代表——图标本身就是应用,点击后在图标下方弹出毛玻璃面板,失焦自动收起:

tinyjs 菜单栏常驻托盘应用 World Clock 的世界时钟面板

注意两点:该模式仍需已登录的图形会话(不是服务器模式);WebKit 关闭窗口后可能保留缓存的 worker 进程,空窗口列表不等于内存已完全释放。

跨平台差异与打包发布

托盘相关行为在不同系统上的差异,主要集中在 Linux:

  • Linux 托盘走 AppIndicator/StatusNotifier,本质是菜单式图标,"裸点图标"是通过合成菜单项模拟的;tray.position() 返回 null,下拉面板请改用居中定位;
  • Windows/Linux 上 setHideOnClose 只在"有东西能把应用唤回来"时生效——有托盘图标就不算问题;
  • 缺系统组件时,tiny.system.requirements(['tray']) 能告诉你托盘能力是否可用,promptMissing() 会弹一个带"复制安装命令"按钮的原生对话框,用户不用手敲包名。

发布与常驻:

  • tinyjs build 产出独立可执行文件和(macOS)代码签名好的 .app 包;
  • 开机自启一行调用:await tiny.app.launchAtLogin.set(true)(开发模式下不可用,需打包版);
  • 自动更新:在 tinyjs.json 的 update.url 指向你托管的 manifest 即可。

参考资料

从 tinyjs new 到 tinyjs build,一个菜单栏常驻、全局快捷键唤出、关窗不退出、空闲占用仅十几 MB 的托盘应用,总共只需要改一个 JSON 开关和几十行后端代码——这就是 tinyjs 做系统托盘应用的完整攻略。

登录后查看全文
tinyjsapp