进程间通信

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

IPC 通道

In Electron, processes communicate by passing messages through developer-defined "channels" with the ipcMain and ipcRenderer modules. 这些通道是任意（您可以随意命名它们）和双向（您可以在两个模块中使用相同的通道名称）的。

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

了解上下文隔离进程

Before proceeding to implementation details, you should be familiar with the idea of using a preload script to import Node.js and Electron modules in a context-isolated renderer process.

For a full overview of Electron's process model, you can read the process model docs.
For a primer into exposing APIs from your preload script using the contextBridge module, check out the context isolation tutorial.

模式 1：渲染器进程到主进程（单向）

To fire a one-way IPC message from a renderer process to the main process, you can use the ipcRenderer.send API to send a message that is then received by the ipcMain.on API.

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

对于此演示，您需要将代码添加到主进程、渲染器进程和预加载脚本。完整代码如下，我们将在后续章节中对每个文件进行单独解释。

docs/fiddles/ipc/pattern-1 (33.2.1)Open in Fiddle

main.js
preload.js
index.html
renderer.js

const { app, BrowserWindow, ipcMain } = require('electron/main')
const path = require('node:path')

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

  ipcMain.on('set-title', (event, title) => {
    const webContents = event.sender
    const win = BrowserWindow.fromWebContents(webContents)
    win.setTitle(title)
  })

  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

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

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

<!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="./renderer.js"></script>
  </body>
</html>

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

1. Listen for events with `ipcMain.on`

In the main process, set an IPC listener on the set-title channel with the ipcMain.on API:

main.js (Main Process)
const { app, BrowserWindow, ipcMain } = require('electron')
const path = require('node: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()
})
// ...

The above handleSetTitle callback has two parameters: an IpcMainEvent structure and a title string. 每当消息通过 set-title 通道传入时，此函数找到附加到消息发送方的 BrowserWindow 实例，并在该实例上使用 win.setTitle API。

info

请确保您为以下步骤加载了 index.html 和 preload.js 入口点！

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

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

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

preload.js (Preload Script)
const { contextBridge, ipcRenderer } = require('electron')

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

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

安全警告

We don't directly expose the whole ipcRenderer.send API for security reasons. 确保尽可能限制渲染器对 Electron API 的访问。

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="./renderer.js"></script>
  </body>
</html>

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

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

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

模式 2：渲染器进程到主进程（双向）

双向 IPC 的一个常见应用是从渲染器进程代码调用主进程模块并等待结果。 This can be done by using ipcRenderer.invoke paired with ipcMain.handle.

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

对于此演示，您需要将代码添加到主进程、渲染器进程和预加载脚本。完整代码如下，我们将在后续章节中对每个文件进行单独解释。

docs/fiddles/ipc/pattern-2 (33.2.1)Open in Fiddle

main.js
preload.js
index.html
renderer.js

const { app, BrowserWindow, ipcMain, dialog } = require('electron/main')
const path = require('node:path')

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

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

app.whenReady().then(() => {
  ipcMain.handle('dialog:openFile', handleFileOpen)
  createWindow()
  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

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

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

<!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>

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

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

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

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

关于错误处理

在主进程中通过 handle 引发的错误是不透明的，因为它们被序列化了，并且只有原始错误的 message 属性会提供给渲染器进程。详情请参阅 [#24427]（https://github.com/electron/electron/issues/24427）。

main.js (Main Process)
const { app, BrowserWindow, dialog, ipcMain } = require('electron')
const path = require('node:path')

// ...

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

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

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

关于通道名称

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

info

请确保您为以下步骤加载了 index.html 和 preload.js 入口点！

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

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

preload.js (Preload Script)
const { contextBridge, ipcRenderer } = require('electron')

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

安全警告

We don't directly expose the whole ipcRenderer.invoke API for security reasons. 确保尽可能限制渲染器对 Electron API 的访问。

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 元素，将用于显示所选文件的路径。要使这些部分起作用，需要在渲染器进程脚本中编写几行代码：

renderer.js (Renderer Process)
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 元素中显示选中文件的路径。

注意：对于旧方法

ipcRenderer.invoke API 是在 Electron 7 中添加的，作为处理渲染器进程中双向 IPC 的一种开发人员友好的方式。 However, a couple of alternative approaches to this IPC pattern exist.

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

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

info

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

使用 `ipcRenderer.send`

我们用于单向通信的 ipcRenderer.send API 也可用于双向通信。这是在 Electron 7 之前通过 IPC 进行异步双向通信的推荐方式。

preload.js (Preload Script)
// 您也可以使用 `contextBridge` API
// 将这段代码暴露给渲染器进程
const { ipcRenderer } = require('electron')

ipcRenderer.on('asynchronous-reply', (_event, arg) => {
  console.log(arg) // 在 DevTools 控制台中打印“pong”
})
ipcRenderer.send('asynchronous-message', 'ping')

main.js (Main Process)
ipcMain.on('asynchronous-message', (event, arg) => {
  console.log(arg) // 在 Node 控制台中打印“ping”
  // 作用如同 `send`，但返回一个消息
  // 到发送原始消息的渲染器
  event.reply('asynchronous-reply', 'pong')
})

这种方法有几个缺点：

您需要设置第二个 ipcRenderer.on 监听器来处理渲染器进程中的响应。使用 invoke，您将获得作为 Promise 返回到原始 API 调用的响应值。
没有显而易见的方法可以将 asynchronous-reply 消息与原始的 asynchronous-message 消息配对。如果您通过这些通道非常频繁地来回传递消息，则需要添加其他应用代码来单独跟踪每个调用和响应。

使用 `ipcRenderer.sendSync`

ipcRenderer.sendSync API 向主进程发送消息，并同步等待响应。

main.js (Main Process)
const { ipcMain } = require('electron')
ipcMain.on('synchronous-message', (event, arg) => {
  console.log(arg) // 在 Node 控制台中打印“ping”
  event.returnValue = 'pong'
})

preload.js (Preload Script)
// 您也可以使用 `contextBridge` API
// 将这段代码暴露给渲染器进程
const { ipcRenderer } = require('electron')

const result = ipcRenderer.sendSync('synchronous-message', 'ping')
console.log(result) // 在 DevTools 控制台中打印“pong”

这份代码的结构与 invoke 模型非常相似，但出于性能原因，我们建议避免使用此 API。它的同步特性意味着它将阻塞渲染器进程，直到收到回复为止。

模式 3：主进程到渲染器进程

将消息从主进程发送到渲染器进程时，需要指定是哪一个渲染器接收消息。 Messages need to be sent to a renderer process via its WebContents instance. This WebContents instance contains a send method that can be used in the same way as ipcRenderer.send.

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

对于此演示，您需要将代码添加到主进程、渲染器进程和预加载脚本。完整代码如下，我们将在后续章节中对每个文件进行单独解释。

docs/fiddles/ipc/pattern-3 (33.2.1)Open in Fiddle

main.js
preload.js
index.html
renderer.js

const { app, BrowserWindow, Menu, ipcMain } = require('electron/main')
const path = require('node: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')

  // Open the DevTools.
  mainWindow.webContents.openDevTools()
}

app.whenReady().then(() => {
  ipcMain.on('counter-value', (_event, value) => {
    console.log(value) // will print value to Node console
  })
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

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

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

<!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>

const counter = document.getElementById('counter')

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

1. 使用 `webContents` 模块发送消息

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

main.js (Main Process)
const { app, BrowserWindow, Menu, ipcMain } = require('electron')
const path = require('node: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')
}
// ...

出于本教程的目的，请务必注意， click 处理函数通过 update-counter 通道向渲染器进程发送消息（1 或 -1）。

click: () => mainWindow.webContents.send('update-counter', -1)

info

请确保您为以下步骤加载了 index.html 和 preload.js 入口点！

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

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

preload.js (Preload Script)
const { contextBridge, ipcRenderer } = require('electron')

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

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

安全警告

We don't directly expose the whole ipcRenderer.on API for security reasons. 确保尽可能限制渲染器对 Electron API 的访问。 Also don't just pass the callback to ipcRenderer.on as this will leak ipcRenderer via event.sender. Use a custom handler that invoke the callback only with the desired arguments.

info

在这个最小示例中，您可以直接在预加载脚本中调用 ipcRenderer.on ，而不是通过 context bridge 暴露它。

preload.js (Preload Script)
const { ipcRenderer } = require('electron')

window.addEventListener('DOMContentLoaded', () => {
  const counter = document.getElementById('counter')
  ipcRenderer.on('update-counter', (_event, value) => {
    const oldValue = Number(counter.innerText)
    const newValue = oldValue + value
    counter.innerText = newValue
  })
})

但是，与通过 context bridge 暴露预加载 API 相比，此方法的灵活性有限，因为监听器无法直接与渲染器代码交互。

3. 构建渲染器进程 UI

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

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>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 (Renderer Process)
const counter = document.getElementById('counter')

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

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

可选：返回一个回复

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

我们可以对前面例子的代码进行略微修改来演示这一点。 In the renderer process, expose another API to send a reply back to the main process through the counter-value channel.

preload.js (Preload Script)
const { contextBridge, ipcRenderer } = require('electron')

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

renderer.js (Renderer Process)
const counter = document.getElementById('counter')

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

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

main.js (Main Process)
// ...
ipcMain.on('counter-value', (_event, value) => {
  console.log(value) // will print value to Node console
})
// ...

模式 4：渲染器进程到渲染器进程

没有直接的方法可以使用 ipcMain 和 ipcRenderer 模块在 Electron 中的渲染器进程之间发送消息。为此，您有两种选择：

将主进程作为渲染器之间的消息代理。这需要将消息从一个渲染器发送到主进程，然后主进程将消息转发到另一个渲染器。
Pass a MessagePort from the main process to both renderers. 这将允许在初始设置后渲染器之间直接进行通信。

对象序列化

Electron 的 IPC 实现使用 HTML 标准的结构化克隆算法来序列化进程之间传递的对象，这意味着只有某些类型的对象可以通过 IPC 通道传递。

特别是 DOM 对象（例如 Element，Location 和 DOMMatrix），Node.js 中由 C++ 类支持的对象（例如 process.env，Stream 的一些成员）和 Electron 中由 C++ 类支持的对象（例如 WebContents、BrowserWindow 和 WebFrame）无法使用结构化克隆序列化。

IPC 通道​

了解上下文隔离进程​

模式 1：渲染器进程到主进程（单向）​

1. Listen for events with ipcMain.on​

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

3. 构建渲染器进程 UI​

模式 2：渲染器进程到主进程（双向）​

1. 使用 ipcMain.handle 监听事件​

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

3. 构建渲染器进程 UI​

注意：对于旧方法​

使用 ipcRenderer.send​

使用 ipcRenderer.sendSync​

模式 3：主进程到渲染器进程​

1. 使用 webContents 模块发送消息​

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

3. 构建渲染器进程 UI​

可选：返回一个回复​

模式 4：渲染器进程到渲染器进程​

对象序列化​

IPC 通道

了解上下文隔离进程

模式 1：渲染器进程到主进程（单向）

1. Listen for events with `ipcMain.on`

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

3. 构建渲染器进程 UI

模式 2：渲染器进程到主进程（双向）

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

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

3. 构建渲染器进程 UI

注意：对于旧方法

使用 `ipcRenderer.send`

使用 `ipcRenderer.sendSync`

模式 3：主进程到渲染器进程

1. 使用 `webContents` 模块发送消息

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

3. 构建渲染器进程 UI

可选：返回一个回复

模式 4：渲染器进程到渲染器进程

对象序列化