Skip to content

自定义窗口 ​

插件可以打开额外的系统窗口,比如悬浮的便签、置顶的计时器、贴图。窗口里的页面同样能用 window.ling,窗口之间可以互发消息。不需要权限。

createBrowserWindow ​

ts
createBrowserWindow(url: string, options?: BrowserWindowOptions, callback?: () => void): Promise<LingBrowserWindow>
  • url:插件目录内页面的相对路径,可以带 ?query 和 #hash,如 'dist/float.html?id=1'。不能是网址或绝对路径。
  • callback:页面第一次加载完成时调用。
ts
const win = await window.ling.createBrowserWindow('dist/float.html', {
  width: 320,
  height: 200,
  alwaysOnTop: true,
  frame: false,
  transparent: true,
})

开发时注意

开发版的主页面从开发服务加载,但自建窗口的页面总是从插件目录读取。所以要先构建出窗口页面(多页面的 Vite 配置可以用 build.rollupOptions.input),或开 vite build --watch。

选项 ​

选项说明
width / height尺寸,默认 800 × 600
minWidth / minHeight / maxWidth / maxHeight尺寸限制
x / y位置(两个都给时生效)
center居中
show创建后是否显示,默认 true
title标题
resizable能否调整大小,默认 true
alwaysOnTop置顶
frame是否有系统标题栏与边框,默认 true
transparent窗口透明
backgroundColor背景色
fullscreen全屏
skipTaskbar不在任务栏显示(macOS 上不生效)

为兼容 uTools,其他 Electron 选项会被接受但忽略。

窗口句柄 ​

返回的 LingBrowserWindow 的方法都是异步的:

分类方法
显示show() hide() focus() close() destroy() minimize() maximize() unmaximize() restore() setFullScreen(flag) reload()
状态isDestroyed() isVisible() isFocused() isMaximized() isFullScreen()
尺寸位置setSize(w, h) getSize() setPosition(x, y) getPosition() setBounds(rect) getBounds() center() setMinimumSize(w, h) setMaximumSize(w, h)
其他setResizable(flag) setAlwaysOnTop(flag) setTitle(title) getTitle()
页面webContents.send(channel, ...args) 给窗口页面发消息;webContents.executeJavaScript(code) 在窗口页面里执行脚本

id 为窗口 ID,parentId 为创建它的自建窗口 ID(由主页面创建时为 null)。尺寸指内容区(不含标题栏)。

找回句柄(比如主页面重新加载后):

方法说明
browserWindow.getCurrent()当前页面所在的自建窗口
browserWindow.fromId(id)按 ID 找回
browserWindow.getAll()本插件打开的全部自建窗口

窗口间消息 ​

ts
// 主页面 → 窗口
await win.webContents.send('update', { text: '新内容' })

// 窗口页面里接收
window.ling.ipc.on('update', (event, payload) => {
  // event.senderId:发送方窗口 ID,主页面发来的为 null
  render(payload.text)
})

// 窗口 → 创建它的页面
await window.ling.sendToParent('closed', { id: 1 })
// 窗口 → 插件主页面(主页面在后台时照常投递)
await window.ling.ipc.sendToHost('saved')
// 发给任意窗口
await window.ling.ipc.sendTo(otherWindowId, 'ping')

消息参数必须能序列化为 JSON,单条不超过 1 MiB。

生命周期 ​

  • 自建窗口里的页面和主页面属于同一个插件:数据、权限相同,可以调用大部分 ling.*,但不能调用作用于插件界面的方法(outPlugin、子输入框、setExpandHeight 等),getWindowType() 为 'custom'。
  • 插件开着自建窗口时,用户按 Esc 退出插件只会退到后台,不会销毁;最后一个窗口关闭时,如果插件不允许后台运行,插件随之结束。
  • outPlugin(true) 或「结束运行」会关闭插件的全部自建窗口。
  • 自建窗口没有自己的 preload,和主页面共用插件的 Node 后端。