@quiteer/electron-ipc

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

Electron 主进程 IPC 预设通道：一次 init()，渲染进程即可安全地操作所属窗口、调用 node:path 能力。

包内不持有任何全局状态，所有窗口操作都来自 event.sender 定位的窗口，渲染进程无法越权操作别的窗口。

安装

pnpm add @quiteer/electron-ipc

快速开始

主进程里初始化：

import { Ipc } from '@quiteer/electron-ipc'
import { app } from 'electron'

app.whenReady().then(() => {
  Ipc.init()
})

渲染进程里按枚举发消息（需配合预加载脚本暴露的 window.$ipc）：

import { EventKeys, IpcWindowOptions } from '@quiteer/electron-ipc/web'

// 最大化当前窗口
window.$ipc.send(EventKeys.WindowOptionsKey, IpcWindowOptions.MAXIMIZE)

// 拼路径, 返回 Promise
const full = await window.$ipc.invoke(EventKeys.FileOptionsKey, 'join', '/user', 'local')

内置通道

__window_options__ — 窗口控制

send 单向发送，操作对象是发起调用的窗口自身。

枚举	值	说明
DESTROY	destroy	销毁窗口，触发 closed
CLOSE	close	尝试关闭，等同点关闭按钮（页面可拦截）
SHOW	show	显示
HIDE	hide	隐藏
FOCUS	focus	获取焦点
BLUR	blur	失去焦点
MAXIMIZE	maximize	最大化
UNMAXIMIZE	unmaximize	取消最大化
MINIMIZE	minimize	最小化
RESTORE	restore	从最小化还原
RELOAD	reload	刷新
SET_FULL_SCREEN	setFullScreen	全屏，附 flag: boolean
SET_TITLE	setTitle	改标题，附 title: string
FLASH_FRAME	flashFrame	任务栏闪烁，附 flag: boolean
SWITCH_FOCUS	switch-focus	聚焦 / 失焦互切
SWITCH_MAX	switch-max	最大化 / 还原互切
SWITCH_MIN	switch-min	最小化 / 还原互切
SWITCH_FULL	switch-full	全屏 / 退出全屏互切
SWITCH_RESIZABLE	switch-resizable	可否调整尺寸互切
SWITCH_MOVABLE	switch-movable	可否移动互切（Linux 无效）
SWITCH_MINIMIZABLE	switch-minimizable	可否最小化互切（Linux 无效）
SWITCH_MAXIMIZABLE	switch-maximizable	可否最大化互切（Linux 无效）
SWITCH_ALWAYS_ON_TOP	switch-always-on-top	是否置顶互切

带参数的调用：

window.$ipc.send(EventKeys.WindowOptionsKey, IpcWindowOptions.SET_TITLE, '新标题')
window.$ipc.send(EventKeys.WindowOptionsKey, IpcWindowOptions.SET_FULL_SCREEN, true)

__file_options__ — 路径处理

invoke 双向调用，返回 Promise，等价于在主进程里调用 node:path 的同名方法。

枚举	值	等价方法
BASENAME	basename	path.basename(path, suffix?)
DIRNAME	dirname	path.dirname(path)
EXTNAME	extname	path.extname(path)
JOIN	join	path.join(...paths)
PARSE	parse	path.parse(path)
RELATIVE	relative	path.relative(from, to)
RESOLVE	resolve	path.resolve(...paths)

const dir = await window.$ipc.invoke(EventKeys.FileOptionsKey, 'dirname', '/a/b/c.txt')
const info = await window.$ipc.invoke(EventKeys.FileOptionsKey, 'parse', '/a/b/c.txt')

渲染层类型增强

包内提供 ExpandPreloadIpc，叠加在预加载的 $ipc 类型上即可获得通道与参数的补全和校验：

// global.d.ts
interface Window {
  $ipc: import('@quiteer/electron-preload').PreloadIpc & import('@quiteer/electron-ipc/web').ExpandPreloadIpc
}

之后写错通道或漏传参数都会直接报错：

window.$ipc.send('__window_options__', 'destroy') // ✅
window.$ipc.invoke('__file_options__', 'join', '/', '/experiment') // ✅
window.$ipc.send('__window_options__', 'not-exist') // ❌ 类型报错

与 @quiteer/electron-browser 配合

本包按 event.sender 定位窗口，若你还需要按名管理窗口，可在自己的业务通道里用 browser 的仓库反查来源：

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

API

Ipc 是单例，直接取用即可。

成员	说明
Ipc.init()	注册两个内置通道的监听与处理器
Ipc.destroy()	注销监听与处理器，应用退出前或热重载时调用

注意事项

• 只需在主进程 app.whenReady() 之后 init()；重复 init() 会叠加 ipcMain.on 监听，建议与 destroy() 成对使用。
• 窗口类操作只作用于发起调用的窗口，渲染进程无法指定其他窗口——这是刻意的约束。
• 通道常量统一走 EventKeys，不要手写字符串，避免拼写漂移。
• 包为 ESM-only：主进程需使用 ESM，或交由打包器（electron-builder / vite / esbuild）一起编译。CJS 主进程直接 require() 会抛 ERR_PACKAGE_PATH_NOT_EXPORTED。