tinyjs 窗口控制终极指南:无边框、透明、置顶、多窗口与原生拖拽一次全懂
tinyjs 窗口控制终极指南:无边框、透明、置顶、多窗口与原生拖拽一次全懂
tinyjs 是一个用 JS 写原生桌面应用(Backend + Frontend)的轻量框架,打包后仅约 6MB。本文聚焦 tinyjs 窗口控制(window control):无边框、透明、置顶、多窗口与原生拖拽五大能力,全部由 tiny.win.* 一行 API 驱动,macOS、Windows、Linux 三平台行为一致 🪟。
为什么 tinyjs 的窗口控制对新手友好
传统 Electron 应用要控制窗口形态,往往需要主进程 + BrowserWindow 选项 + 各平台补丁。tinyjs 的页面端直接注入了 tiny 全局对象(无需任何 <script> 引入),窗口相关能力全部集中在 tiny.win 命名空间下:
- 声明式:启动外观写进 tinyjs.json 的
"chrome"字段,首帧渲染前生效,不会闪一下默认标题栏; - 命令式:运行时随时
setChrome、setSize、setPosition、setAlwaysOnTop,全部 Promise 安全; - 事件化:
tiny.win.onState推送每一次窗口状态变化(全屏、最小化、聚焦……),不必轮询。
完整类型定义见 types/tiny.d.ts,所有 API 速查在 skill/references/api.md。
无边框窗口:一行去掉标题栏
想让应用看起来"不像浏览器",第一步就是去掉系统标题栏:
tiny.win.setChrome({ frame: false, windowControls: false, vibrancy: 'hud' });
或者在 tinyjs.json 中声明,打包应用会在首次绘制前应用,彻底避免"先闪标题栏再消失"的观感问题:
{ "chrome": { "frame": false, "windowControls": false } }
几个关键细节:
- 保留红绿灯?
windowControls可设为true、false或['close','minimize']数组,按平台映射到对应系统按钮; - 方形圆角:macOS 默认圆角窗口,
squareCorners: true切换为方形无边框形态,同样建议在 JSON 里声明以免启动闪烁; - 第一击即响应:
acceptsFirstMouse: true让"点击聚焦"的那一下同时触达页面,是调色板、工具条类 HUD 的标配; - 固定尺寸(如 Winamp 式播放台)配合
tiny.win.setResizable(false),用户拖不动边缘,但你的setSize依然有效。
💡 平台差异提醒:Windows 上"透明主窗口"必须在 tinyjs.json 里预先声明;无边框/透明窗口在 Windows 上不会绘制菜单栏。详见 skill/references/platforms.md。
透明窗口与毛玻璃质感
transparent 与 vibrancy 是做出"悬浮感"面板的两个开关:
tiny.win.setChrome({ transparent: true, vibrancy: 'hud' });
transparent: true:窗口背景透明,页面 CSS 想画什么形状就画什么形状;vibrancy:macOS 专属毛玻璃材质(如'hud'),页面背景留空即可获得系统级模糊。
透明 + 无边框 + 置顶三件套,就是典型的 HUD、桌宠、悬浮时钟的做法,现成菜谱见 skill/references/recipes.md(Desktop pet / overlay 一节)。
置顶与悬浮层:从工具栏到桌面壁纸级
tinyjs 把"窗口层级"拆成了两个维度:
tiny.win.setAlwaysOnTop(true); // 保持在普通窗口之上
tiny.win.setLevel('overlay'); // 'normal' | 'floating' | 'overlay' | 'desktop'
tiny.win.setClickThrough(true); // 鼠标事件穿透
| 方法 | 典型场景 |
|---|---|
setAlwaysOnTop(true) |
字幕条、常驻工具面板 |
setLevel('overlay') |
覆盖全屏应用的 HUD |
setLevel('desktop') |
壁纸级桌宠(在所有窗口之后) |
setClickThrough(true) |
纯展示型浮层,鼠标直接穿过去 |
setAllSpaces(true) |
跟随 macOS 每个桌面空间 / Linux 粘滞窗口 |
配套技巧:tiny.win.show({ activate: false }) 可以把悬浮面板"展示出来但不抢焦点",做 HUD 时非常关键。
多窗口管理:设置面板、子窗口一步到位
前端目录里任何一个 HTML 文件都能开成新窗口,tiny.win.open 一次搞定页面、尺寸、位置和外观:
tiny.win.open('settings', {
page: 'settings.html', title: 'Settings',
size: '420x300', x: 40, y: 40,
chrome: { frame: false }
});
值得记住的四个点:
chrome和x/y在窗口绘制前就生效 —— 无边框面板开出来即是最终形态,不会"居中闪跳";parent: true绑定父子关系:子窗口始终盖在父窗口之上(不会盖住你的其他应用),随父窗口一起最小化/隐藏/关闭,Windows 与 Linux 上还不占任务栏;- 每个窗口都有完整的
tiny.*桥,页面里的tiny.win.*永远只操作"自己"; - 后端统一调度:
app.openWindow(id, opts)、app.window(id).*操作任意窗口,export function onWindowClosed(id, app)监听关闭。
四个真实窗口、可拖拽吸附的播放器实例,展示了多窗口在 tinyjs 里的真实形态:
原生拖拽:移动窗口、拖文件、拉伸边缘
去掉标题栏后"怎么移动窗口"是新手最常卡住的点。tinyjs 的答案是 HTML 属性:
<header data-tiny-drag>按住我拖动窗口</header>
- 拖拽即可移动窗口,双击该区域等于最大化/还原(zoom);
- 区域内的按钮、输入框等交互子元素自动排除,不需要逐一手写;个别想排除的元素加
data-tiny-nodrag; - 不想用属性时,手动调用
tiny.win.startDrag()效果相同。
文件拖拽是"真路径"而非浏览器里那种 blob:
tiny.win.onDrop((paths) => tiny.log(paths.join(', '))); // 拖入:真实文件路径
row.addEventListener('mousedown', () =>
tiny.win.startDrag({ files: [path] })); // 拖出:拖到 Finder/Slack
无边框窗口的边缘缩放也不用自己画手柄:macOS 保留原生边缘;Linux 和 Windows 的次级无边框窗口会自动加一圈不可见的 5px 抓握区;想自定义手柄就用 tiny.win.startResize('se')(支持 n/ne/e/se/s/sw/w/nw 八个方向)。固定尺寸窗口可声明 <html data-tiny-noresize> 或 setResizable(false) 退出自动抓握。
窗口状态:读、听、救
const s = await tiny.win.getState(); // x/y、宽高、全屏/最小化/聚焦、chrome 配置…
const off = tiny.win.onState(({ win, focused }) => {}); // 任何状态变化都推送
width/height是"页面盒子"尺寸(不含装饰),原样回传setSize不会跑位;onState不区分变化来源——绿点、菜单、F11 或你自己的调用都算,事件自带窗口 id,多窗口场景按win过滤即可;- 外接显示器热插拔后窗口跑到屏幕外?启动时会自动"救回"最近屏幕(
offscreenRescue),也可手动tiny.win.ensureOnScreen()。
平台差异速查表
| 能力 | macOS | Windows | Linux |
|---|---|---|---|
| 无边框 + 透明 | ✅ 完整 | ✅ 主窗口透明需 JSON 预声明 | ✅ 依赖 GTK/WM |
vibrancy 毛玻璃 |
✅ | — | — |
setLevel/setAllSpaces |
✅ | —(setAllSpaces 不支持) |
setAllSpaces 映射为粘滞窗口 |
窗口自定位(setPosition) |
✅ | ✅ | ⚠️ 纯 Wayland 下受限,tinyjs.json 加 "windowPlacement": true 走 XWayland |
不确定当前机器能做什么,问 tiny.system.capabilities()——它只列出"例外项",按 caps.x !== false 判断即可。逐平台细节见 skill/references/platforms.md。
延伸阅读
- 完整
tiny.win.*API 与坑点注释:skill/references/api.md - 桌宠 / 覆盖层 / 托盘应用菜谱:skill/references/recipes.md
- 官方文档与项目说明:README.md、docs/docs.html
- 运行时窗口客户端实现:runtime/tiny.js
- 可自驱动的窗口测试页:test/smoke.html
掌握以上五个模块,你已经在 tinyjs 里拥有了"原生桌面感"的全部窗口能力——接下来,去写一个属于自己的 6MB 小应用吧 ✅




