ipcRenderer
- 方法
- 事件对象

ipcRenderer

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

进程: Renderer

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

请参阅进程间通信（IPC）教程获取代码示例。

方法

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 将抛出异常

主进程应该使用 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.send。

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

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

请注意 如果主进程中的处理程序出现错误，由 invoke 返回的 promise 将被 reject。然而，渲染器进程中的 Error 对象将与主进程中的对象不同。

`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
  // ...
})

更多关于如何使用 MessagePort 和 MessageChannel的信息详见 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一节中找到