跳到主要内容

ipcRenderer

历史

从渲染器进程异步地与主进程通信。

进程: 渲染器

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

请参阅 IPC 教程 以获取代码示例。

方法

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

ipcRenderer.on(channel, listener)

监听 channel,当新消息到达时,将使用 listener(event, args...) 调用 listener

警告

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

ipcRenderer.off(channel, listener)

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

ipcRenderer.once(channel, listener)

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

ipcRenderer.addListener(channel, listener)

ipcRenderer.on 的别名。

ipcRenderer.removeListener(channel, listener)

ipcRenderer.off 的别名。

ipcRenderer.removeAllListeners([channel])

  • channel 字符串 (可选)

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

ipcRenderer.send(channel, ...args)

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

通过 channel 向主进程发送异步消息,以及参数。 参数将使用 结构化克隆算法 序列化,就像 window.postMessage 一样,因此不会包含原型链。 发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

注意: 发送非标准的 JavaScript 类型,例如 DOM 对象或特殊的 Electron 对象,将抛出异常。

由于主进程不支持 DOM 对象,例如 ImageBitmapFileDOMMatrix 等,因此这些对象无法通过 Electron 的 IPC 发送到主进程,因为主进程无法解码它们。 尝试通过 IPC 发送此类对象将导致错误。

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

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

如果你想从主进程接收单个响应,例如方法调用的结果,请考虑使用 ipcRenderer.invoke

ipcRenderer.invoke(channel, ...args)

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

返回 Promise<any> - 使用来自主进程的响应进行解析。

通过 channel 向主进程发送消息并异步地期望结果。 参数将使用 结构化克隆算法 序列化,就像 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 对象,将抛出异常。

由于主进程不支持 DOM 对象,例如 ImageBitmapFileDOMMatrix 等,因此这些对象无法通过 Electron 的 IPC 发送到主进程,因为主进程无法解码它们。 尝试通过 IPC 发送此类对象将导致错误。

注意 如果主进程中的处理程序抛出错误,则 invoke 返回的 Promise 将被拒绝。 但是,渲染器进程中的 Error 对象将与主进程中抛出的对象不同。

ipcRenderer.sendSync(channel, ...args)

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

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

通过 channel 向主进程发送消息并同步地期望结果。 参数将使用 结构化克隆算法 序列化,就像 window.postMessage 一样,因此不会包含原型链。 发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。

注意: 发送非标准的 JavaScript 类型,例如 DOM 对象或特殊的 Electron 对象,将抛出异常。

由于主进程不支持 DOM 对象,例如 ImageBitmapFileDOMMatrix 等,因此这些对象无法通过 Electron 的 IPC 发送到主进程,因为主进程无法解码它们。 尝试通过 IPC 发送此类对象将导致错误。

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

⚠️ 警告: 发送同步消息将阻塞整个渲染器进程,直到收到回复,因此仅在万不得已的情况下使用此方法。 最好使用异步版本,invoke()

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

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

向主进程发送消息,可以选择性地传输零个或多个 MessagePort 对象的所有权。

传输的 MessagePort 对象将在主进程中作为 MessagePortMain 对象提供,通过访问发出的事件的 ports 属性。

例如

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

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

有关使用 MessagePortMessageChannel 的更多信息,请参阅 MDN 文档

ipcRenderer.sendToHost(channel, ...args)

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

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