如何用 tinyjs 打造系统托盘应用?菜单栏常驻、全局快捷键与窗口隐藏完全攻略
如何用 tinyjs 打造系统托盘应用?菜单栏常驻、全局快捷键与窗口隐藏完全攻略
tinyjs 是一个用纯 JavaScript 构建原生桌面应用的轻量框架(约 6MB,无 Electron、无 Node、无打包的浏览器内核),它对系统托盘应用提供了开箱即用的支持:菜单栏常驻图标、原生右键菜单、全局快捷键唤出窗口、关闭窗口只隐藏不退出,甚至"零窗口"的纯托盘 Agent 模式都内置好了。本文将带你从零完成一个菜单栏常驻应用的完整思路与关键配置。
为什么选择 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,完整生命周期就是:
- 启动 → 菜单栏出现图标,窗口隐藏;
- 点击托盘"显示窗口" →
app.window('main').show(); - 用户点关闭按钮 → 窗口隐藏,后端和托盘图标原样保留;
- 只有
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 演示了标准生命周期:
- 启动时
app.windows()为空,只有托盘图标在运行; - 点菜单"Open editor" →
app.openWindow('editor', { page: 'editor.html' })按需创建窗口; - 关掉该窗口后,后端和托盘继续存活,可以再次打开;
- 点"Quit" →
app.quit()真正退出。
这种模式不需要 index.html,甚至不需要 src/frontend/ 目录,tinyjs build 就能打包。官方菜单栏时钟 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 即可。
参考资料
- 托盘与无窗口 Agent 的完整说明:README.md
- 托盘应用模板与避坑要点:skill/references/recipes.md
- 全量 API 速查(tray / hotkey / presence / windows):skill/references/api.md
- 可运行的无窗口托盘示例:test/windowless-tray/
- 安装脚本:docs/install
从 tinyjs new 到 tinyjs build,一个菜单栏常驻、全局快捷键唤出、关窗不退出、空闲占用仅十几 MB 的托盘应用,总共只需要改一个 JSON 开关和几十行后端代码——这就是 tinyjs 做系统托盘应用的完整攻略。

