@neosjs/electron-toolkit
Electron 桌面端工具集 monorepo,包含三个子包:@neosjs/electron-toolkit(主进程 / 渲染进程 / preload 三端管理器)、@neosjs/electron-preload(独立的 preload 安全桥)与 @neosjs/downloader(基于 got 的流式下载器)。三者覆盖了 Electron 应用开发中窗口、存储、更新、下载、IPC 暴露等高频能力,均可单独安装使用。
安装
pnpm add @neosjs/electron-toolkitnpm i @neosjs/electron-toolkityarn add @neosjs/electron-toolkit环境要求
Node.js >= 22。@neosjs/electron-toolkit 的部分能力依赖可选 peer 依赖(electron-log、electron-updater、fs-extra、got 等),按需安装即可。
@neosjs/electron-toolkit
按进程拆分为三个入口,均导出单例管理器:
// 渲染进程
import NeosRenderer from '@neosjs/electron-toolkit' // 或 '@neosjs/electron-toolkit/renderer'
// 主进程
import NeosMain from '@neosjs/electron-toolkit/main'
// preload
import { exposeElectronAPI } from '@neosjs/electron-toolkit/preload'主进程(./main)
主入口导出单例 NeosMain(NeosMainManager.getInstance() 获取),聚合了 15 个单例管理器,覆盖桌面应用主进程的常见职责:
| 属性 | 职责 |
|---|---|
appManager | 应用生命周期 |
windowManager | 窗口管理 |
ipcManager | IPC 管理 |
updaterManager | 自动更新 |
downloaderManager | 下载管理 |
storageManager / fileManager | 存储 / 文件 |
systemManager | 系统信息 |
mediaManager | 媒体权限 |
autoLaunch | 开机自启 |
energyManager | 电源阻塞 |
devtool | 开发者工具 |
themeManager | 系统主题 |
exceptionManager | 异常捕获 |
logger | 日志(electron-log) |
应用就绪后调用 init 完成窗口与更新器初始化:
import NeosMain from '@neosjs/electron-toolkit/main'
import { BrowserWindow } from 'electron'
NeosMain.init({
browserWindow: win as BrowserWindow,
updater: {
autoCheck: true, // 自动检查更新
autoDownload: false, // 自动下载
autoInstallOnAppQuit: true // 退出时自动安装
}
})init 的配置项类型 InitOptions:
interface InitOptions {
browserWindow: BrowserWindow | null
updater?: UpdaterOptions
shortcutOptions?: ShortcutOptions
}不再需要时调用 NeosMain.destroy() 释放全部管理器。
渲染进程(./renderer)
导出单例 NeosRenderer,属性包括:logger、downloadManager、storageManager、windowManager、systemManager、mediaManager、fileManager、updaterManager、emitter(事件管理)与 themeManager;另提供 getLogger(name) 获取按模块隔离的日志实例。
import NeosRenderer from '@neosjs/electron-toolkit/renderer'
const theme = await NeosRenderer.themeManager.getSystemTheme()渲染端入口还导出 ipcRenderer 代理与自定义标题栏元素 TitleBar(继承 HTMLElement,自定义元素名为 title-bar,支持明暗双主题与 nominimize / nomaximize / noclose 等属性控制窗口按钮)。
preload(./preload)
导出 exposeElectronAPI() 与 NeosElectronApi:exposeElectronAPI() 在开启 contextIsolation 时通过 contextBridge.exposeInMainWorld('__NEOS_ELECTRON__API__', ...) 暴露 API,否则直接挂到 window。暴露面包括:
ipcRenderer:send/sendSync/invoke/postMessage/sendToHost/on/once/removeListener/removeAllListeners(on/once返回取消监听函数)webFrame:insertCSS/setZoomFactor/setZoomLevelwebUtils:getPathForFileprocess:platform/versions/env
@neosjs/electron-preload
独立的 preload 安全桥包,与 @neosjs/electron-toolkit/preload 能力一致,适合只想引入 preload 桥、不引入其余管理器的项目。peer 依赖 electron(可选项)。
// src/preload/index.ts
import { exposeElectronAPI } from '@neosjs/electron-preload'
exposeElectronAPI()与非隔离环境不同,该包会同时将 API 暴露为 window.electron、window.electronApi 与 window.__NEOS_ELECTRON__API__ 三个全局,兼容不同取用习惯。
@neosjs/downloader
纯 Node 流式下载器,导出 NeDownloader 类(继承 EventEmitter),基于 got 与 fs-extra(两者为 peer 依赖,需自行安装)。
import { NeDownloader } from '@neosjs/downloader'
const downloader = new NeDownloader({
timeout: { send: 5000 }, // 发送超时
retry: { limit: 5 } // 重试次数
})
downloader.on('progress', (p) => {
console.log(`进度:${p.percent * 100}%`)
})
downloader.on('completed', (res) => {
console.log('完成:', res.filePath)
})
downloader.on('fail', (err) => {
console.error('失败:', err)
})
// 直接传 URL,文件名从 URL 推断
await downloader.start('https://example.com/file.zip')
// 或传完整选项
await downloader.start({
url: 'https://example.com/file.zip',
filePath: '/path/to/file.zip',
onProgress: async (p) => { /* p 为进度信息 */ },
onError: async (err) => { console.error(err) }
})
// 中止 / 销毁
downloader.abort()
downloader.destroy()行为要点:
- 目标文件已存在时跳过下载,直接以
progress(percent 为 1)与completed(含文件 md5)事件收尾; - 默认重试 5 次,覆盖 408 / 413 / 429 / 5xx 状态码与常见网络错误码;
- 事件面:
progress、completed、fail、end、closed、destroy; - 下载选项(
Options):url、filePath、md5?、onProgress?、onError?、onClosed?、onEnd?;构造器选项(BaseOptions)透传 got 的signal/timeout/retry。