Poros-基于 Umi 的 Electron React 框架

基于 Umi 的 Electron React 框架

您可以快速构建一个 Electron 项目，可以开发、打包、升级等，它具备 Umi 的所有功能。它还集成了常用的 electron 库，比如：electron-log 、electron-store... 未来还将集成更多功能。

快速上手

创建项目

先找个地方建个空目录。

$ mkdir myapp && cd myapp

# pnpm 推荐
$ pnpm create poros

# npm
$ npx create-poros@latest

# yarn
$ yarn create poros

启动项目

执行 pnpm start 命令

        ╔═══════════════════════════════╗
ready - ║  Electron app launch success  ║
        ╚═══════════════════════════════╝
event - [Webpack] Compiled in 19830 ms (4955 modules)
info  - [MFSU][eager] write cache
info  - [MFSU] buildDepsAgain
info  - [MFSU] skip buildDeps

目录结构

├── config
│   ├── builder.ts                      // electron-builder 配置
│   ├── config.ts                       // umi 配置
│   └── routes.ts                       // umi routes 配置
├── mock                                
│   └── demo.ts
├── src
│   ├── constants
│   │   └── index.ts
│   ├── locales                         // 国际化目录,开启国际化插件有效
│   │   ├── en-US.ts
│   │   └── zh-CN.ts
│   ├── main                            // 主进程目录
│   │   ├── windows                     // 窗口目录
│   │   └── index.ts
│   ├── preload                         // preload 目录
│   │   └── index.ts
│   ├── renderer                        // 渲染进程目录，同 umi
│   │   ├── assets
│   │   ├── models
│   │   ├── pages
│   │   ├── utils 
│   │   ├── ipc.ts                      // 渲染进程与主进程 ipc 通信定义文件，开启 ipc 插件有效
│   │   └── app.ts         
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
└── typings.d.ts

自定义窗口

框架约定以 src/main/window 目录作为自定定窗口目录

自定义窗口需要继承 PorosBrowserWindow 类, PorosBrowserWindow 为 BrowserWindow 子类

// src/main/window/MainWindow
import path from 'path';
import { PorosBrowserWindow, PorosBrowserWindowOptions } from 'poros';

class MainWindow extends PorosBrowserWindow {
  /**
   * 是否单例, 默认：true
   */
  static readonly single = true;

  /**
   * 加载页面地址
   */
  protected static readonly URL = '/';

  /**
   * 窗口属性配置
   */
  protected static readonly OPTIONS: PorosBrowserWindowOptions = {
    title: 'Poros',
    height: 628,
    width: 542,
    minHeight: 628,
    minWidth: 542,
    hideOnClose: true,
    webPreferences: {
      preload: path.join(__dirname, 'preload/index.js'),
    },
  };

  constructor() {
    super(MainWindow.URL, MainWindow.OPTIONS);
  }

  protected registerWindowEvent(): void {}
}

export default MainWindow;

API

import { something } from 'poros';

Main Process

Renderer Process

透传 umi 的所有属性, 也加入了一些写的属性

PorosBrowserWindow

继承至 BrowserWindow

PorosWindowManager

管理 PorosBrowserWindow 窗口

Logger

配置项 config/config.ts

export default defineConfig({
   logger : {
     transports: {
       file: {
         level: 'warn',
         format: '[{y}-{m}-{d} {h}:{i}:{s}.{ms}] [{level}]{scope} {text}',
         maxSize: 1048576,
       },
       console: {
         level: 'debug',
       },
     },
   }
});

具体配置和用法可参照electron-log。

注意：控制台的日志输出为了作出类型区分加了特有的标志，所有 transports.console.format 的设置不会生效,

LocalStore

保存用户设置、应用程序状态、缓存等

配置项 config/config.ts

export default defineConfig({
   localStore: {
     schema: {
       unicorn: {
          type: 'string',
         default: '🦄',
       },
     },
   },
});

具体配置和用法可参照electron-store。

LocalShortcut

将键盘快捷键本地添加到 BrowserWindow 实例，而不使用菜单

PorosBrowserWindow 中内置了打开 DevTools 快捷键 Cmd+Option+I 或 F12

具体用法可参照electron-localshortcut。

插件

您也可以直接使用 Umi 插件。如果您遇到任何问题，请联系我。

locale

与 umi locale 插件功能基本相同，开启方法一致，主进程与渲染进程中使用方法相同。

import { localeInfo, getIntl, setIntl, getLocale, setLocale, getAllLocales, i18n } from 'poros';

i18n('button.ok');

ipc

简化主进程与渲染进程之间的通信

主进程 API

rendererInvoker 中 broadcast 为 true 时，会给所有窗口广播事件(广播事件无返回值)，所有监听了事件的窗口都会收到消息，反之只有相应的窗口下页面会收到消息。PorosBrowserWindow 类中调用，window 默认值为当前窗口，非PorosBrowserWindow 类中必需指定 window 值。

渲染进程 API

渲染进程调用主进程

// 1 、使用 IpcHandle 注解要调用的方法
import { IpcHandle } from 'poros';
class MainWindow extends PorosBrowserWindow {
  // ... 省略基本属性

  @IpcHandle
  foo(name: string) {
    return 'Hello renderer'; // 返回给渲染进程
  }
}

export default MainWindow;

// 2 、渲染进程中调用
import { mainInvoker } from 'poros';
const ret = mainInvoker.MainWindow.foo('demo');

主进程调用渲染进程

1 、定义事件类型(/src/renderer/ipc.ts)

export default interface IpcChannelToHandlerMap {
  'network-monitor': (received: number, transferred: number) => string;
}

2 、react 组件中监听

import { mainInvoker } from 'poros';

const Demo = () => {
  useIpc('network-monitor', (received, transferred) => {
    return ''; // 返回值给主进程
  });
  // 或者
  const [received, transferred] = useIpc('network-monitor');

  return (
    <div>demo</div>
  );
};
export default Demo;

3 、主进程中调用

// PorosBrowserWindow 类中调用
const ret = this.rendererInvoker.networkMonitor(received: number, transferred: number, opts?: { broadcast?: boolean, window?: PorosBrowserWindow}); 

// 非 PorosBrowserWindow 类中调用
import { rendererInvoker } from 'poros';
rendererInvoker.networkMonitor(received: number, transferred: number, opts: { broadcast?: boolean, window: PorosBrowserWindow });

预设插件

• initial-state
• access
• model
• react-query
• antd
• locale
• ipc

DEMO 预览图

来个 Star🙏🙏🙏

https://github.com/porosjs/poros