@quiteer/electron-browser

属于 electron-modules 系列，与 electronup 配套使用。源码见 packages/browser。

Electron 主进程窗口管理：统一注册、随处取窗、响应式操作。

安装

pnpm add @quiteer/electron-browser

快速开始

import { windows } from '@quiteer/electron-browser'

// 创建并注册
const main = windows.create({
  name: 'main',
  width: 1200,
  height: 800,
  url: 'https://example.com'
})

main.title = '我的应用' // 直接改属性即可
main.centered = true

// 任意位置、任意时刻按名取窗
windows.get('main')?.webContents.send('ping')
windows.focus('main')

窗口名称类型安全

// windows.ts
import { createWindowManager } from '@quiteer/electron-browser'

export const windows = createWindowManager<'main' | 'settings'>()

windows.create({ name: 'main' })
windows.get('settings') // ✅ 有补全
windows.get('setting') // ❌ 类型报错

响应式属性

窗口句柄在 BrowserWindow 之上补充了一组可直接读写的属性，读写都会同步到真实窗口：

属性	读	写
width / height	getSize()	setSize()，只改一边不影响另一边
x / y	getPosition()	setPosition()
title	getTitle()	setTitle()
visible	isVisible()	show() / hide()
centered	—	置 true 触发 center()

其余属性与方法全部透传 BrowserWindow（方法已绑定 this），原始实例通过 controller.target 获取，controller.raw 是它的等价别名。

const main = windows.getController('main')!

main.webContents.send('ping') // 透传方法, 无需关心 this
main.target // 原生 BrowserWindow
main.name // 'main'

创建选项

在 BrowserWindowConstructorOptions 基础上扩展：

选项	类型	说明
name	string	必填，窗口唯一标识
url	string	创建后立即 loadURL
openDevTools	boolean	创建后立即打开开发者工具
showOnReady	boolean	未显式 show: true 时，在 ready-to-show 后自动显示，默认 true
conflict	'focus' | 'recreate' | 'error'	同名窗口已存在时的策略，默认 focus

策略	行为
focus（默认）	沿用旧窗口并聚焦，直接返回原句柄，不会创建新窗口
recreate	关闭旧窗口后重建
error	直接抛错，适合「只允许单例」的窗口

register() 同名注册时只覆盖映射，不会关闭旧窗口——外部创建的窗口生命周期由你自己负责。

API

WindowManager

方法	说明
create(options)	创建窗口并注册，返回控制句柄
register(name, win)	把外部创建的窗口纳入管理
get(name)	按名取 BrowserWindow，无则 undefined
getController(name)	按名取带响应式属性的句柄
getOrThrow(name)	按名取窗，缺失时抛错
has(name)	窗口是否存在
focus(name)	还原并聚焦，不存在返回 false
close(name)	关闭窗口，不存在返回 false
closeAll()	关闭全部窗口（Promise，等所有 closed 完成）
broadcast(channel, ...args)	向所有窗口广播消息
list() / names() / size	窗口清单

WinStore

窗口仓库，可单独使用。窗口 closed 时自动摘除映射，取窗时校验 isDestroyed()，不会拿到已销毁的窗口。

store.fromId(id) // 按窗口 id 反查句柄
store.fromWebContents(webContents) // 按 webContents（或其 id）反查
store.getName(win) // 按实例（或 id）反查名称
store.entries() // [name, controller][]
store.remove(name) // 摘除注册（不关闭窗口）
store.clear() // 清空注册表
store.closeAll() // 关闭全部（等待 closed 后清空）

fromWebContents() 用于在 ipc 回调里定位来源窗口，配合自己定义的业务通道很顺手：

import { ipcMain } from 'electron'
import { windows } from '@quiteer/electron-browser'

ipcMain.on('custom', (event) => {
  const controller = windows.store.fromWebContents(event.sender)
  controller?.target.webContents.send('custom:reply', controller.name)
})