Skip to content

@neosjs/electron-toolkit ​

Electron 桌面端工具集 monorepo,包含三个子包:@neosjs/electron-toolkit(主进程 / 渲染进程 / preload 三端管理器)、@neosjs/electron-preload(独立的 preload 安全桥)与 @neosjs/downloader(基于 got 的流式下载器)。三者覆盖了 Electron 应用开发中窗口、存储、更新、下载、IPC 暴露等高频能力,均可单独安装使用。

安装 ​

sh
pnpm add @neosjs/electron-toolkit
sh
npm i @neosjs/electron-toolkit
sh
yarn add @neosjs/electron-toolkit

环境要求

Node.js >= 22。@neosjs/electron-toolkit 的部分能力依赖可选 peer 依赖(electron-log、electron-updater、fs-extra、got 等),按需安装即可。

@neosjs/electron-toolkit ​

按进程拆分为三个入口,均导出单例管理器:

ts
// 渲染进程
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窗口管理
ipcManagerIPC 管理
updaterManager自动更新
downloaderManager下载管理
storageManager / fileManager存储 / 文件
systemManager系统信息
mediaManager媒体权限
autoLaunch开机自启
energyManager电源阻塞
devtool开发者工具
themeManager系统主题
exceptionManager异常捕获
logger日志(electron-log)

应用就绪后调用 init 完成窗口与更新器初始化:

ts
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:

ts
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) 获取按模块隔离的日志实例。

ts
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 / setZoomLevel
  • webUtils:getPathForFile
  • process:platform / versions / env

@neosjs/electron-preload ​

独立的 preload 安全桥包,与 @neosjs/electron-toolkit/preload 能力一致,适合只想引入 preload 桥、不引入其余管理器的项目。peer 依赖 electron(可选项)。

ts
// 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 依赖,需自行安装)。

ts
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。