ipcRenderer

历史

版本	变更
None	ipcRenderer 不再能通过 contextBridge 发送

在渲染进程和主进程之间进行异步通信。

进程：渲染进程

ipcRenderer 模块是一个 EventEmitter。它提供了一些方法，可以让你从渲染进程（网页）向主进程发送同步和异步消息。你也可以接收来自主进程的回复。

请参阅 IPC 教程 查看代码示例。

方法

ipcRenderer 模块有以下方法用于监听事件和发送消息

ipcRenderer.on(channel, listener)

• channel 字符串
• listener 函数
  • event IpcRendererEvent
  • ...args any[]

监听 channel，当新的消息到达时，listener 会以 listener(event, args...) 调用。

警告

出于安全原因，请勿将 event 参数暴露给渲染器！请将从渲染器接收到的任何回调函数包裹在另一个函数中，例如：ipcRenderer.on('my-channel', (event, ...args) => callback(...args))。不这样做会导致危险的 Electron API 暴露给渲染进程。请参阅安全指南 了解更多信息。

ipcRenderer.off(channel, listener)

• channel 字符串
• listener 函数
  • event IpcRendererEvent
  • ...args any[]

移除指定 channel 监听器数组中的指定 listener。

ipcRenderer.once(channel, listener)

• channel 字符串
• listener 函数
  • event IpcRendererEvent
  • ...args any[]

为事件添加一次性 listener 函数。该 listener 仅在下次向 channel 发送消息时调用，之后即被移除。

ipcRenderer.addListener(channel, listener)

• channel 字符串
• listener 函数
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.on 的别名。

ipcRenderer.removeListener(channel, listener)

• channel 字符串
• listener 函数
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.off 的别名。

ipcRenderer.removeAllListeners([channel])

• channel 字符串 (可选)

移除指定 channel 的所有监听器。如果未指定 channel，则移除所有 channel 的所有监听器。

ipcRenderer.send(channel, ...args)

• channel 字符串
• ...args any[]

通过 channel 向主进程发送异步消息，并携带参数。参数将使用 Structured Clone Algorithm 进行序列化，就像 window.postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 会抛出异常。

注意： 发送非标准 JavaScript 类型（如 DOM 对象或特殊的 Electron 对象）会抛出异常。

由于主进程不支持 ImageBitmap、File、DOMMatrix 等 DOM 对象，因此这些对象无法通过 Electron 的 IPC 发送给主进程，因为主进程无法解码它们。尝试通过 IPC 发送此类对象会导致错误。

主进程使用 ipcMain 模块通过监听 channel 来处理此消息。

如果你需要将 MessagePort 传输到主进程，请使用 ipcRenderer.postMessage。

如果你想从主进程接收单个回复（例如方法调用的结果），请考虑使用 ipcRenderer.invoke。

ipcRenderer.invoke(channel, ...args)

• channel 字符串
• ...args any[]

返回 Promise<any> - resolves 时带有来自主进程的回复。

通过 channel 向主进程发送消息并异步等待结果。参数将使用 Structured Clone Algorithm 进行序列化，就像 window.postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 会抛出异常。

主进程应该使用 ipcMain.handle() 监听 channel。

例如

// Renderer process
ipcRenderer.invoke('some-name', someArgument).then((result) => {
  // ...
})

// Main process
ipcMain.handle('some-name', async (event, someArgument) => {
  const result = await doSomeWork(someArgument)
  return result
})

如果你需要将 MessagePort 传输到主进程，请使用 ipcRenderer.postMessage。

如果你不需要消息的回复，请考虑使用 ipcRenderer.send。

注意 发送非标准 JavaScript 类型（如 DOM 对象或特殊的 Electron 对象）会抛出异常。

由于主进程不支持 ImageBitmap、File、DOMMatrix 等 DOM 对象，因此这些对象无法通过 Electron 的 IPC 发送给主进程，因为主进程无法解码它们。尝试通过 IPC 发送此类对象会导致错误。

注意 如果主进程中的处理程序抛出错误，invoke 返回的 Promise 将会拒绝。但是，渲染进程中的 Error 对象与主进程中抛出的错误对象不会完全相同。

ipcRenderer.sendSync(channel, ...args)

• channel 字符串
• ...args any[]

返回 any - 由 ipcMain 处理程序返回的值。

通过 channel 向主进程发送消息并同步等待结果。参数将使用 Structured Clone Algorithm 进行序列化，就像 window.postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 会抛出异常。

注意： 发送非标准 JavaScript 类型（如 DOM 对象或特殊的 Electron 对象）会抛出异常。

由于主进程不支持 ImageBitmap、File、DOMMatrix 等 DOM 对象，因此这些对象无法通过 Electron 的 IPC 发送给主进程，因为主进程无法解码它们。尝试通过 IPC 发送此类对象会导致错误。

主进程使用 ipcMain 模块通过监听 channel 来处理此消息，并通过设置 event.returnValue 进行回复。

⚠️ 警告：发送同步消息会阻塞整个渲染进程，直到收到回复，因此只应在万不得已时才使用此方法。最好使用异步版本 invoke()。

ipcRenderer.postMessage(channel, message, [transfer])

• channel 字符串
• message any
• transfer MessagePort[] (可选)

向主进程发送消息，可选地转移零个或多个 MessagePort 对象的拥有权。

被传输的 MessagePort 对象将通过访问触发事件的 ports 属性在主进程中作为 MessagePortMain 对象可用。

例如

// Renderer process
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])

// Main process
ipcMain.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

有关使用 MessagePort 和 MessageChannel 的更多信息，请参阅 MDN 文档。

ipcRenderer.sendToHost(channel, ...args)

• channel 字符串
• ...args any[]

类似于 ipcRenderer.send，但事件将发送到宿主页面中的 <webview> 元素，而不是主进程。