用 tinyjs 打造桌面宠物与 HUD 覆盖层:窗口池化、穿透点击与桌面层级控制实战

原创2026-10-16 15:32:301,723 阅读

用 tinyjs 打造桌面宠物与 HUD 覆盖层:窗口池化、穿透点击与桌面层级控制实战

tinyjs 是一个体积极小的 JS 桌面应用框架:一个 txiki.js 后端 + 原生 webview 窗口,安装包仅约 6MB,没有 Electron、没有 Node、没有捆绑的 Chromium。它提供的无框透明窗口、setClickThrough 鼠标穿透、setLevel 桌面层级控制和多窗口管理 API,让桌面宠物和 HUD 覆盖层这类"悬浮在桌面上"的应用变得异常简单——本文带你实战掌握这套技巧。

tinyjs 桌面应用框架:约 6MB 的轻量级构建工具横幅

为什么 tinyjs 适合做桌面悬浮类应用 🪶

传统方案里,做桌面宠物往往要写原生窗口、处理 DPI、自己管多窗口,或者背上 Electron 这个几百 MB 的大包袱。而 tinyjs 的应用本质就是"纯 HTML/CSS/JS 前端 + 有完整系统权限的 JS 后端",页面跑在系统 WebKit(macOS/Linux)或 WebView2(Windows)里:

  • 多窗口是原生能力:tiny.win.open() 一次打开一个独立窗口,每个窗口都是真实的 webview,互不干扰
  • 窗口即页面:任何前端 HTML 文件都可以成为一个窗口,宠物、覆盖层、面板各占一个窗口
  • 无 HTTP 服务器、无端口:前后端通过私有临时目录里的 Unix domain socket 通信,天然安全且零配置

下面这张图是 tinyjs 官方演示之一 "Tiny Deck",一个窗口里同时演示了 WebGPU、WASM、FFI 等能力,也说明了框架的性能上限:

Tiny Deck 演示应用:tinyjs 多能力展示窗口,含 WebGPU 渲染与系统状态栏

核心 API 速查:窗口"超能力"一览 🎯

做桌面宠物和 HUD,只需要记住几个关键 API(前端和后端两侧都可用):

API 作用 典型场景
tiny.win.setClickThrough(true) 鼠标事件穿透窗口,点击落在后面的应用上 纯展示型覆盖层、桌宠
tiny.win.setLevel('normal' / 'floating' / 'overlay' / 'desktop') 控制窗口桌面层级:desktop 沉到所有窗口后面(壁纸宠物),overlay 浮在全屏应用之上 桌宠、游戏 HUD
tiny.win.setAllSpaces(true) 跟随用户跨 Space 移动,并浮于全屏应用之上 常驻 HUD
tiny.win.show({ activate: false }) 显示窗口但不抢焦点 弹出 HUD、面板
tiny.win.open(id, { chrome: { frame: false, transparent: true } }) 打开无框透明窗口 宠物本体

这些定义可以直接在 runtime/tiny.js 中看到,完整的 TypeScript 类型在 template/types/tiny.d.ts。

打造一只"点不穿"的桌面宠物 🐾

桌宠的灵魂是两点:鼠标要能穿过去、层级要可控。关键代码只有三行:

// 打开一只无框、透明、可穿透的宠物窗口
tiny.win.open('pet', {
  page: 'pet.html',
  size: '240x240',
  chrome: { frame: false, transparent: true },  // ← 必须在 open 时传入
});
tiny.win.setClickThrough(true);   // 点击穿透到后面的应用
tiny.win.setLevel('desktop');     // 沉到桌面壁纸层(可选)

⚠️ 最大的坑:chrome 配置必须写在 win.open 的参数里,由启动器在首次绘制前应用。如果你在新窗口的启动代码里才调用 setChrome,宠物会先"闪"成一个默认的白色窗口再变透明——官方配方文件里明确记录了这一点。

几个实战要点(源自 skill/references/recipes.md 的官方配方):

  • 无框窗口拖拽:给页面上的头部区域加 data-tiny-drag 属性,即可获得原生窗口拖拽,双击还能放大
  • 伪深度排序:两只宠物交叉走过时,按从后到前的顺序重新调用 show(),就能产生"谁在前谁在后"的立体感
  • Linux 注意:无框窗口会被窗口管理器自动加上边缘缩放手柄,务必给宠物窗口声明 minSize,否则内容可能被拉出可视区

这张图是 tinyjs 的 Platter 黑胶播放器示例,一个典型的无框沉浸窗口,展示了透明无边框窗口的视觉效果:

Platter 黑胶播放器:tinyjs 无框透明窗口示例,桌面悬浮应用风格

打造不抢焦点的 HUD 覆盖层 👁️

HUD(Heads-Up Display)与桌宠的诉求相反:它要浮在一切之上,但不能抢走焦点——用户在打游戏、看视频时,你的 HUD 悄悄出现,不打断任何操作。

tiny.win.setLevel('overlay');            // 浮在全屏应用之上
tiny.win.setAllSpaces(true);             // 跟随跨 Space 移动
tiny.win.show({ activate: false });     // 显示,但绝不抢焦点

三行组合拳的效果:全屏游戏中弹出的战绩面板、悬浮在视频上的字幕条、常驻桌面的迷你时钟……都是这个配方。下面这张 World Clock 截图就是典型的 HUD 风格悬浮面板——深色毛玻璃、无干扰、独立于桌面其他应用:

World Clock HUD 悬浮时钟面板:dark 风格桌面覆盖层,展示不抢焦点的悬浮 UI

补充两个细节:

  • macOS 上给 HUD 加毛玻璃质感:tiny.win.setChrome({ vibrancy: 'hud' })
  • 想让"点击聚焦"那一下也直接作用到页面上(比如快速调色面板),给窗口加 acceptsFirstMouse: true

性能关键:窗口池化,别反复创建销毁 ⚡

这是官方性能指南里最值钱的一句话:窗口隐藏很便宜,反复创建销毁很贵(skill/references/performance.md):

Windows are cheap to hide and expensive to churn — pool and reuse (show/move/hide) instead of create/destroy in a loop.

每个窗口都是一个真实的 webview,创建/销毁要重新初始化渲染进程;而"隐藏 + 移动 + 复用"几乎零成本。官方示例 coo3d 的玩法是:第 9 个特效出现时,回收最老的那个窗口——用户完全看不出来,但内存和 CPU 纹丝不动。

配合一个必须知道的机制:被遮挡/隐藏的窗口会被 WebKit 节流(rAF 停止、定时器变慢)。所以正确的架构是:

  • 大脑放后端:后端定时器永远不被节流,让它以约 25fps 的 tick 驱动整个模拟
  • 窗口只负责画:每个 tick 向各窗口 push 一次状态,窗口收到就渲染
  • 小消息要合并:一个 tick 一条聚合消息,而不是每个属性发一条(官方示例 20+ 窗口只靠 25fps 的单条 tick 消息驱动)

下面的 Amp 示例应用(桌面版 Winamp)展示了 tinyjs 的多窗口能力——四个真实窗口自由摆放、还能吸附停靠,正是窗口池化思路的理想载体:

Amp 桌面音乐播放器:tinyjs 四窗口应用示例,窗口可吸附停靠,演示多窗口管理

跨平台差异一览(macOS / Windows / Linux) 🖥️

能力 macOS Windows Linux
setClickThrough ✅ ✅ ✅
setLevel(四级层级) ✅ ✅ ✅
setAllSpaces ✅(跟 Space + 压全屏) ❌(capabilities 中会如实上报) 映射为 sticky 窗口
无框窗口缩放手柄 无 主窗口保留真实边框 有,需声明 minSize
vibrancy: 'hud' 毛玻璃 ✅ ❌ ❌

建议用 tiny.system.capabilities() 做特性探测(检测 caps.x !== false),而不是写死平台分支——不支持的能力会安静地 no-op,查询类返回 null,不会挂起。完整平台差异见 skill/references/platforms.md。

另外,如果你的"宠物"其实是个后台托盘应用(不显示主窗口),可以在 tinyjs.json 里声明 { "activation": "accessory", "mainWindow": false },参考 test/windowless-tray/tinyjs.json——空闲内存占用比带主窗口的模式低一大截(macOS 上约 17 MiB 对 65 MiB)。

相关文件导读 📚

总结:用 tinyjs 做桌面宠物与 HUD,本质就是三步——win.open 时传入 chrome 拿无框透明窗口、setClickThrough + setLevel 控制穿透与层级、用后端 tick + 窗口池化驱动多窗口。三个 API、一行配置,一个几 MB 的应用就能在桌面上"活"起来。

登录后查看全文
tinyjsapp