tinyjs 窗口控制终极指南:无边框、透明、置顶、多窗口与原生拖拽一次全懂

原创2026-10-16 17:22:382,001 阅读

tinyjs 窗口控制终极指南:无边框、透明、置顶、多窗口与原生拖拽一次全懂

tinyjs 是一个用 JS 写原生桌面应用(Backend + Frontend)的轻量框架,打包后仅约 6MB。本文聚焦 tinyjs 窗口控制(window control):无边框、透明、置顶、多窗口与原生拖拽五大能力,全部由 tiny.win.* 一行 API 驱动,macOS、Windows、Linux 三平台行为一致 🪟。

tinyjs 窗口控制总览:用 JS 构建的原生桌面应用

为什么 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 依然有效。

tinyjs 无边框窗口示例:自定义控制按钮的记录播放器

💡 平台差异提醒: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 透明窗口示例:悬浮 HUD 风格的多城市时钟面板

置顶与悬浮层:从工具栏到桌面壁纸级

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 }
});

tinyjs 多窗口示例:Markdown 主编辑窗口与浮动子窗口

值得记住的四个点:

  1. chrome 和 x/y 在窗口绘制前就生效 —— 无边框面板开出来即是最终形态,不会"居中闪跳";
  2. parent: true 绑定父子关系:子窗口始终盖在父窗口之上(不会盖住你的其他应用),随父窗口一起最小化/隐藏/关闭,Windows 与 Linux 上还不占任务栏;
  3. 每个窗口都有完整的 tiny.* 桥,页面里的 tiny.win.* 永远只操作"自己";
  4. 后端统一调度:app.openWindow(id, opts)、app.window(id).* 操作任意窗口,export function onWindowClosed(id, app) 监听关闭。

四个真实窗口、可拖拽吸附的播放器实例,展示了多窗口在 tinyjs 里的真实形态:

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。

延伸阅读

掌握以上五个模块,你已经在 tinyjs 里拥有了"原生桌面感"的全部窗口能力——接下来,去写一个属于自己的 6MB 小应用吧 ✅

登录后查看全文
tinyjsapp