09 【进程间通信】

进程间通信 (IPC) 是在 Electron 中构建功能丰富的桌面应用程序的关键部分之一。由于主进程和渲染器进程在 Electron 的进程模型具有不同的职责，因此 IPC 是执行许多常见任务的唯一方法，例如从 UI 调用原生 API 或从原生菜单触发 Web 内容的更改。

官方文档：

ipcMain

ipcRenderer

webContents

1.IPC 通道

在 Electron 中，进程使用 ipcMain 和 ipcRenderer 模块，通过开发人员定义的“通道”传递消息来进行通信。这些通道是任意（您可以随意命名它们）和 ** 双向** （您可以在两个模块中使用相同的通道名称）的。

我们将介绍一些基本的 IPC 模式，并提供具体的示例。您可以将这些示例作为您应用程序代码的参考。

2.渲染器进程到主进程（单向）

要将单向 IPC 消息从渲染器进程发送到主进程，您可以使用 ipcRenderer.send API 发送消息，然后使用 ipcMain.on API 接收。

通常使用此模式从 Web 内容调用主进程 API。我们将通过创建一个简单的应用来演示此模式，可以通过编程方式更改它的窗口标题。

2.1 使用 `ipcMain.on` 监听事件

在主进程中，使用 ipcMain.on API 在 set-title 通道上设置一个 IPC 监听器:

main.js

const {app, BrowserWindow, ipcMain} = require('electron')
const path = require('path')

//...

function handleSetTitle (event, title) {
  const webContents = event.sender
  const win = BrowserWindow.fromWebContents(webContents)
  win.setTitle(title)
}

function createWindow () {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })
  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  ipcMain.on('set-title', handleSetTitle)
  createWindow()
}
//...

上面的 handleSetTitle 回调函数有两个参数：一个 IpcMainEvent 结构和一个 title 字符串。每当消息通过 set-title 通道传入时，此函数找到附加到消息发送方的 BrowserWindow 实例，并在该实例上使用 win.setTitle API。

2.2 通过预加载脚本暴露 `ipcRenderer.send`

要将消息发送到上面创建的监听器，您可以使用 ipcRenderer.send API。默认情况下，渲染器进程没有权限访问 Node.js 和 Electron 模块。作为应用开发者，您需要使用 contextBridge API 来选择要从预加载脚本中暴露哪些 API。

在您的预加载脚本中添加以下代码，向渲染器进程暴露一个全局的 window.electronAPI 变量。

preload.js

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('electronAPI', {
    setTitle: (title) => ipcRenderer.send('set-title', title)
})

此时，您将能够在渲染器进程中使用 window.electronAPI.setTitle() 函数。

安全警告

出于安全原因，我们不会直接暴露整个 ipcRenderer.send API。确保尽可能限制渲染器对 Electron API 的访问。

2.3 构建渲染器进程 UI

在 BrowserWindow 加载的我们的 HTML 文件中，添加一个由文本输入框和按钮组成的基本用户界面:

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Hello World!</title>
  </head>
  <body>
    Title: <input id="title"/>
    <button id="btn" type="button">Set</button>
    <script src="./render.js"></script>
  </body>
</html>

为了使这些元素具有交互性，我们将在导入的 renderer.js 文件中添加几行代码，以利用从预加载脚本中暴露的 window.electronAPI 功能：

renderer.js

const setButton = document.getElementById('btn')
const titleInput = document.getElementById('title')
setButton.addEventListener('click', () => {
    const title = titleInput.value
    window.electronAPI.setTitle(title)
});

此时，您的演示应用应该已经功能齐全。尝试使用输入框，看看 BrowserWindow 的标题会发生什么变化！

3.渲染器进程到主进程（双向）

双向 IPC 的一个常见应用是从渲染器进程代码调用主进程模块并等待结果。这可以通过将 ipcRenderer.invoke 与 ipcMain.handle 搭配使用来完成。

在下面的示例中，我们将从渲染器进程打开一个原生的文件对话框，并返回所选文件的路径。

3.1 使用 `ipcMain.handle` 监听事件

在主进程中，我们将创建一个 handleFileOpen() 函数，它调用 dialog.showOpenDialog 并返回用户选择的文件路径值。每当渲染器进程通过 dialog:openFile 通道发送 ipcRender.invoke 消息时，此函数被用作一个回调。然后，返回值将作为一个 Promise 返回到最初的 invoke 调用。

main.js

const { BrowserWindow, dialog, ipcMain } = require('electron')
const path = require('path')

//...

async function handleFileOpen() {
  const { canceled, filePaths } = await dialog.showOpenDialog()
  if (canceled) {
    return
  } else {
    return filePaths[0]
  }
}

function createWindow () {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })
  mainWindow.loadFile('index.html')
}

app.whenReady(() => {
  ipcMain.handle('dialog:openFile', handleFileOpen)
  createWindow()
})
//...

关于通道名称

IPC 通道名称上的 dialog: 前缀对代码没有影响。它仅用作命名空间以帮助提高代码的可读性。

3.2 通过预加载脚本暴露 `ipcRenderer.invoke`

在预加载脚本中，我们暴露了一个单行的 openFile 函数，它调用并返回 ipcRenderer.invoke('dialog:openFile') 的值。我们将在下一步中使用此 API 从渲染器的用户界面调用原生对话框。

preload.js

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('electronAPI', {
  openFile: () => ipcRenderer.invoke('dialog:openFile')
})

安全警告

出于安全原因，我们不会直接暴露整个 ipcRenderer.invoke API。确保尽可能限制渲染器对 Electron API 的访问。

3.3 构建渲染器进程 UI

最后，让我们构建加载到 BrowserWindow 中的 HTML 文件。

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Dialog</title>
  </head>
  <body>
    <button type="button" id="btn">Open a File</button>
    File path: <strong id="filePath"></strong>
    <script src='./renderer.js'></script>
  </body>
</html>

用户界面包含一个 #btn 按钮元素，将用于触发我们的预加载 API，以及一个 #filePath 元素，将用于显示所选文件的路径。要使这些部分起作用，需要在渲染器进程脚本中编写几行代码：

render.js

const btn = document.getElementById('btn')
const filePathElement = document.getElementById('filePath')

btn.addEventListener('click', async () => {
  const filePath = await window.electronAPI.openFile()
  filePathElement.innerText = filePath
})

在上面的代码片段中，我们监听 #btn 按钮的点击，并调用 window.electronAPI.openFile() API 来激活原生的打开文件对话框。然后我们在 #filePath 元素中显示选中文件的路径。

3.4 注意：对于旧方法

ipcRenderer.invoke API 是在 Electron 7 中添加的，作为处理渲染器进程中双向 IPC 的一种开发人员友好的方式。但这种 IPC 模式存在几种替代方法。

如果可能，请避免使用旧方法

我们建议尽可能使用 ipcRenderer.invoke 。出于保留历史的目地，记录了下面双向地渲染器到主进程模式。

INFO

对于以下示例，我们将直接从预加载脚本调用 ipcRenderer，以保持代码示例短小。

4.主进程到渲染器进程

将消息从主进程发送到渲染器进程时，需要指定是哪一个渲染器接收消息。消息需要通过其 WebContents 实例发送到渲染器进程。此 WebContents 实例包含一个 send 方法，其使用方式与 ipcRenderer.send 相同。

为了演示此模式，我们将构建一个由原生操作系统菜单控制的数字计数器。

4.1 使用 `webContents` 模块发送消息

对于此演示，我们需要首先使用 Electron 的 Menu 模块在主进程中构建一个自定义菜单，该模块使用 webContents.send API 将 IPC 消息从主进程发送到目标渲染器。

main.js

const {app, BrowserWindow, Menu, ipcMain} = require('electron')
const path = require('path')

function createWindow () {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  const menu = Menu.buildFromTemplate([
    {
      label: app.name,
      submenu: [
        {
          click: () => mainWindow.webContents.send('update-counter', 1),
          label: 'Increment',
        },
        {
          click: () => mainWindow.webContents.send('update-counter', -1),
          label: 'Decrement',
        }
      ]
    }
  ])
  Menu.setApplicationMenu(menu)

  mainWindow.loadFile('index.html')
}
//...

4.2 通过预加载脚本暴露 `ipcRenderer.on`

与前面的渲染器到主进程的示例一样，我们使用预加载脚本中的 contextBridge 和 ipcRenderer 模块向渲染器进程暴露 IPC 功能：

preload.js

const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('electronAPI', {
    onUpdateCounter: (callback) => ipcRenderer.on('update-counter', callback)
})

加载预加载脚本后，渲染器进程应有权访问 window.electronAPI.onUpdateCounter() 监听器函数。

安全警告

出于安全原因，我们不会直接暴露整个 ipcRenderer.on API。确保尽可能限制渲染器对 Electron API 的访问。

4.3 构建渲染器进程 UI

为了将它们联系在一起，我们将在加载的 HTML 文件中创建一个接口，其中包含一个 #counter 元素，我们将使用该元素来显示值

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Menu Counter</title>
  </head>
  <body>
    Current value: <strong id="counter">0</strong>
    <script src="./renderer.js"></script>
  </body>
</html>

最后，为了更新 HTML 文档中的值，我们将添加几行 DOM 操作的代码，以便在每次触发 update-counter 事件时更新 #counter 元素的值。

renderer.js

const counter = document.getElementById('counter')

window.electronAPI.onUpdateCounter((_event, value) => {
    const oldValue = Number(counter.innerText)
    const newValue = oldValue + value
    counter.innerText = newValue
})

在上面的代码中，我们将回调传递给从预加载脚本中暴露的 window.electronAPI.onUpdateCounter 函数。第二个 value 参数对应于我们传入 webContents.send 函数的 1 或 -1，该函数是从原生菜单调用的。

4.4 可选：返回一个回复

对于从主进程到渲染器进程的 IPC，没有与 ipcRenderer.invoke 等效的 API。不过，您可以从 ipcRenderer.on 回调中将回复发送回主进程。

我们可以对前面例子的代码进行略微修改来演示这一点。在渲染器进程中，使用 event 参数，通过 counter-value 通道将回复发送回主进程。

renderer.js

const counter = document.getElementById('counter')

window.electronAPI.onUpdateCounter((_event, value) => {
    const oldValue = Number(counter.innerText)
    const newValue = oldValue + value
    counter.innerText = newValue
  	_event.sender.send('counter-value', newValue)
})

在主进程中，监听 counter-value 事件并适当地处理它们。

main.js

//...
ipcMain.on('counter-value', (_event, value) => {
  console.log(value) // 将打印到 Node 控制台
})
//...

09 【进程间通信】

1.IPC 通道

2.渲染器进程到主进程（单向）

2.1 使用 ipcMain.on 监听事件

2.2 通过预加载脚本暴露 ipcRenderer.send

2.3 构建渲染器进程 UI

3.渲染器进程到主进程（双向）

3.1 使用 ipcMain.handle 监听事件

3.2 通过预加载脚本暴露 ipcRenderer.invoke

3.3 构建渲染器进程 UI

3.4 注意：对于旧方法

4.主进程到渲染器进程

4.1 使用 webContents 模块发送消息

4.2 通过预加载脚本暴露 ipcRenderer.on

4.3 构建渲染器进程 UI

4.4 可选：返回一个回复

2.1 使用 `ipcMain.on` 监听事件

2.2 通过预加载脚本暴露 `ipcRenderer.send`

3.1 使用 `ipcMain.handle` 监听事件

3.2 通过预加载脚本暴露 `ipcRenderer.invoke`

4.1 使用 `webContents` 模块发送消息

4.2 通过预加载脚本暴露 `ipcRenderer.on`