自定义窗口
插件可以打开额外的系统窗口,比如悬浮的便签、置顶的计时器、贴图。窗口里的页面同样能用 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 后端。