Skip to content

xiefengnian/umijs-electron-plugin

Repository files navigation

@umijs/plugin-electron

🔧 一个基于 umijs 插件体系与前端结合的、用于开发轻量桌面应用的的、简单快速的 electron 开发框架。

安装 Install

Using npm:

$ npm install --save-dev @umijs/plugin-electron

or using yarn:

$ yarn add @umijs/plugin-electron --dev

使用 Usage

基于 umi4 项目开始,请使用 npm create umi 初始化项目。

0. 添加 npm 镜像地址

受国内特殊网络环境影响,需要添加 npm 镜像。

# .npmrc
registry=https://registry.npmmirror.com
electron-mirror=https://registry.npmmirror.com/-/binary/electron/
electron-builder-binaries-mirror=https://registry.npmmirror.com/-/binary/electron-builder-binaries/

1. 配置 config.ts

{
  plugins : ['@umijs/plugin-electron'],
  electron :{},
}

2. 新增 electron 目录

新建文件:src/main/index.ts。因为 plugin-electron 会额外给你一些封装代码,所以目前你什么都不用干。

3. 启动

$ npx umi dev

4. 打包

$ npx umi build

应用产物将会出现在 ~/dist 目录下。

可以参照 example 目录开始

差距说明

为了实现热更新能力,部分和原生开发的差距需要注意:

  1. require.resolve 不可用(因为 require 是伪造的)
  2. app.on(event,listener) 监听 app 事件时,只有第一个 event 会被注册

文档说明

1. 约定式目录

./src/main
├── config.ts // 配置文件
├── forks     // 用于 child_process.fork 的代码文件目录
│   └── init_cli.ts
├── index.ts        // 入口文件
├── ipc       // ipc 通讯文件目录
│   └── index.ts
├── preload.ts      // 用于 browserWindow 的 preload 文件
├── tsconfig.json   // electron 部分的 tsconfig 文件
├── typing.d.ts     // 类型文件
└── util.ts         // 其他文件

约定的目录/文件说明:

  1. 配置文件 config.ts(可选的 optional)

为了实现热更新能力,plugin-electron 代理了 browserWindow 实例的创建。因此,该实例创建的参数需要在 config.ts 定义。

该文件不会热更新,修改后必须重新命令行启动应用生效。

import { BrowserWindowConstructorOptions } from 'electron';

export default {
  browserWindow: {
    width: 400,
    height: 640,
    titleBarStyle: process.platform === 'win32' ? 'hidden' : 'hiddenInset',
    maximizable: false,
  } as BrowserWindowConstructorOptions,
};
  1. forks 目录(可选的 optional)

同样,为了实现热更新能力,其他文件会在编译时有一些额外的代码注入。在 forks 目录下的文件将会跳过热更新的代码注入,仅进行 babel 的编译。

  1. index.ts(必须的 required)

入口文件。

  1. ipc(可选的 optional)

ipc 用于承载 ipc 通讯的文件,该目录下的文件会被自动加载到入口文件中。请不要在该文件中和别的文件互相引用。

  1. preload.ts(可选的 optional)

用于 browserWindow 的 preload。

  1. tsconfig.json(必须 required)

umi 项目使用的 ts 为 web 的。为了使用 node 的类型提示,需要在该目录下添加该文件保证开发体验。

建议根据自身版本安装对应 node 类型提示,例如 node14:$ npm install @tsconfig/node14 --save-dev

{
  "extends": "@tsconfig/node14"
}
  1. typing.d.ts(必须 required)

热更新能力会给所有模块注入 getBrowserWindowRuntime 方法获取当前的 browserWindow 实例。因此,需要额外的类型定义保证研发体验。

import { BrowserWindow } from 'electron';

declare global {
  export function getBrowserWindowRuntime(): BrowserWindow;
}

2. 插件配置

在 umi 中配置 electron 时,支持进行配置:

// src/config/config.ts
export default {
  electron: {},
};

type ElectronConfig = {
  builder: {
    targets: Map<Platform | Map<Arch | Array<String>>>; // https://www.electron.build/api/electron-builder
    config: Configuration; // https://www.electron.build/configuration/configuration
  };
  src: string;
  extraDevFiles: Record<string, string>;
};
  1. builder

构建配置。

targets 和 config 详见 electron-builder 的文档。

example:

// .umirc
import { Platform, Arch } from '@umijs/plugin-electron'; // plugin 中转导出了 electron-builder 的 Programming Api,引入不同的 builder 会导致构建错误

// example: mac & windows
const targets = createTargets([Platform.MAC, Platform.WINDOWS]);

// example: mac m1
const targets = Platform.MAC.createTarget(['dmg'], Arch.arm64);

export default {
  electron: {
    builder: {
      targets: targets,
    },
  },
};
  1. src

研发目录,默认 src/main

  1. 额外的开发阶段文件

需要向开发的临时目录添加的文件,比如热更新所需的证书。建议这样使用:

extraDevFiles: {
  'xxxx.js' : fs.readFileSync('xxxx.js','utf-8'),
}

ISSUE

问题请在 issue 中反馈。