跳到主内容

ipcRenderer

从渲染器进程到主进程的异步通信。

进程: Renderer

ipcRenderer 是一个 EventEmitter 的实例。 你可以使用它提供的一些方法从渲染进程 (web 页面) 发送同步或异步的消息到主进程。 也可以接收主进程回复的消息。

请从 ipcMain 查看代码示例。

方法

ipcRenderer 模块使用以下方法来监听事件和发送消息。

ipcRenderer.on(channel, listener)

  • channel String
  • listener Function
    • event IpcRendererEvent
    • ...args any[]

监听 channel, 当新消息到达,将通过 listener(event, args...) 调用 listener。

ipcRenderer.once(channel, listener)

  • channel String
  • listener Function
    • event IpcRendererEvent
    • ...args any[]

添加一次性 listener 函数。 这个 listener 只会在 channel下一次收到消息的时候被调用,之后这个监听器会被移除。

ipcRenderer.removeListener(channel, listener)

  • channel String
  • listener Function
    • ...args any[]

为特定的 channel 从监听队列中删除特定的 listener 监听者.

ipcRenderer.removeAllListeners(channel)

  • channel String

移除所有的监听器,当指定 channel 时只移除与其相关的所有监听器。

ipcRenderer.send(channel, ...args)

  • channel String
  • ...args any[]

通过channel向主进程发送异步消息,可以发送任意参数。 参数将使用 Structured Clone Algorithm进行序列化,就像 window.postMessage,因此原型链将不会包含在内。 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常

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

主线程不支持 DOM 对象比如 ImageBitmap, File, DOMMatrix 等对象, 它们无法通过Electron的IPC发送到主线程,主要原因是主线程无法对他们进行解码 若尝试通过IPC发送这种对象数据将返回异常

主进程中,通过监听 ipcMain 模块下的 channel 来处理这些消息

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

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

ipcRenderer.invoke(channel, ...args)

  • channel String
  • ...args any[]

Returns Promise<any> - Resolves 主进程返回值

通过 channel 向主过程发送消息,并异步等待结果。 参数将使用 Structured Clone Algorithm进行序列化,就像 window.postMessage,因此原型链将不会包含在内。 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常

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

主线程不支持 DOM 对象比如 ImageBitmap, File, DOMMatrix 等对象, 它们无法通过Electron的IPC发送到主线程,主要原因是主线程无法对他们进行解码 若尝试通过IPC发送这种对象数据将返回异常

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

例如:

// 渲染进程
ipcRenderer.invoke('some-name', someArgument).then((result) => {
// ...
})

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

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

如果你不需要回复此消息,请考虑使用 ipcRender.sent

ipcRenderer.sendSync(channel, ...args)

  • channel String
  • ...args any[]

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

通过 channel 向主过程发送消息,并异步等待结果。 参数将使用 Structured Clone Algorithm进行序列化,就像 window.postMessage,因此原型链将不会包含在内。 发送 Functions, Promises, Symbols, WeakMaps, 或 WeakSets 将抛出异常

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

主线程不支持 DOM 对象比如 ImageBitmap, File, DOMMatrix 等对象, 它们无法通过Electron的IPC发送到主线程,主要原因是主线程无法对他们进行解码 若尝试通过IPC发送这种对象数据将返回异常

主进程可以使用 ipcMain 监听 channel来接收这些消息,并通过 event.returnValue 设置回复消息。

⚠️ 警告: 发送同步消息将阻止整个渲染过程直到收到回复。 这样使用此方法只能作为最后手段。 使用异步版本更好 invoke()

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

  • channel String
  • message any
  • transfer MessagePort[] (optional)

发送消息到主进程,同时可以选择性发送零到多个 MessagePort 对象

从渲染进程发送到主进程的MessagePort对象可作为MessagePortMain对象访问触发事件的ports端口属性

例如:

// 渲染进程
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])

// 主进程
ipcMain.on('port', (e, msg) => {
const [port] = e.ports
// ...
})

更多关于如何使用 MessagePortMessageChannel的信息详见 MDN documentation

ipcRenderer.sendTo(webContentsId, channel, ...args)

  • webContentsId Number
  • channel String
  • ...args any[]

通过 channel 发送消息到带有 webContentsId 的窗口.

ipcRenderer.sendToHost(channel, ...args)

  • channel String
  • ...args any[]

就像 ipcRenderer.send,不同的是消息会被发送到 host 页面上的 <webview> 元素,而不是主进程。

事件对象

callback的参数event对象的文档可以在ipc-renderer-event一节中找到