ipcRenderer

Communicate asynchronously from a renderer process to the main process.从渲染器进程到主进程进行异步通信。

Process:进程：Renderer

The ipcRenderer module is an EventEmitter. ipcRenderer模块是一个EventEmitter。It provides a few methods so you can send synchronous and asynchronous messages from the render process (web page) to the main process. 它提供了一些方法，以便您可以将同步和异步消息从呈现进程（网页）发送到主进程。You can also receive replies from the main process.您还可以接收来自主进程的回复。

See IPC tutorial for code examples.有关代码示例，请参阅IPC教程。

Methods方法

The ipcRenderer module has the following method to listen for events and send messages:ipcRenderer模块具有以下方法来侦听事件和发送消息：

ipcRenderer.on(channel, listener)

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

Listens to channel, when a new message arrives listener would be called with listener(event, args...).侦听channel，当新消息到达时，listener将与listener(event, args...)一起调用。

ipcRenderer.once(channel, listener)

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

Adds a one time listener function for the event. 为事件添加一个一次性listener函数。This listener is invoked only the next time a message is sent to channel, after which it is removed.只有在下一次将消息发送到channel时才会调用此listener，然后将其删除。

ipcRenderer.removeListener(channel, listener)

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

Removes the specified listener from the listener array for the specified channel.从指定channel的侦听器数组中删除指定的listener。

ipcRenderer.removeAllListeners(channel)

• channel string

Removes all listeners, or those of the specified channel.删除所有侦听器或指定channel的侦听器。

ipcRenderer.send(channel, ...args)

• channel string
• ...args any[]

Send an asynchronous message to the main process via channel, along with arguments. 通过channel向主进程发送异步消息以及参数。Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. 参数将使用结构化克隆算法进行序列化，就像window.postMessage一样，因此原型链将不包括在内。Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.发送Function、Promise、Symbol、WeakMap或WeakSet将引发异常。

NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.发送诸如DOM对象或特殊Electron对象之类的非标准JavaScript类型将引发异常。

Since the main process does not have support for DOM objects such as ImageBitmap, File, DOMMatrix and so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. 由于主进程不支持ImageBitmap、File、DOMMatrix等DOM对象，因此这些对象无法通过Electron的IPC发送到主进程，因为主进程无法对它们进行解码。Attempting to send such objects over IPC will result in an error.试图通过IPC发送此类对象将导致错误。

The main process handles it by listening for channel with the ipcMain module.主进程通过ipcMain模块监听channel来处理它。

If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.如果需要将MessagePort传输到主进程，请使用ipcRenderer.postMessage。

If you want to receive a single response from the main process, like the result of a method call, consider using ipcRenderer.invoke.如果您想从主进程接收一个响应，比如方法调用的结果，可以考虑使用ipcRenderer.invoke。

ipcRenderer.invoke(channel, ...args)

• channel string
• ...args any[]

Returns返回Promise<any> - Resolves with the response from the main process.使用来自主进程的响应进行解析。

Send a message to the main process via channel and expect a result asynchronously. 通过channel向主进程发送消息，并期望异步地得到结果。Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. 参数将使用结构化克隆算法进行序列化，就像window.postMessage一样，因此原型链将不包括在内。Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.发送Function、Promise、symbol、Weakmap或WeakSet将抛出异常。

NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.发送诸如DOM对象或特殊Electron对象之类的非标准JavaScript类型将引发异常。

Since the main process does not have support for DOM objects such as ImageBitmap, File, DOMMatrix and so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. 由于主进程不支持ImageBitmap、File、DOMMatrix等DOM对象，因此这些对象无法通过Electron的IPC发送到主进程，因为主进程无法对它们进行解码。Attempting to send such objects over IPC will result in an error.试图通过IPC发送此类对象将导致错误。

The main process should listen for channel with ipcMain.handle().主进程应该使用ipcMain.handle()侦听channel。

For example:例如：

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

If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.如果需要将MessagePort传输到主进程，请使用ipcRenderer.postMessage。

If you do not need a response to the message, consider using ipcRenderer.send.如果您不需要对消息的响应，请考虑使用ipcRenderer.send。

ipcRenderer.sendSync(channel, ...args)

• channel string
• ...args any[]

Returns返回any - The value sent back by the ipcMain handler.ipcMain处理程序发回的值。

Send a message to the main process via channel and expect a result synchronously. 通过channel向主进程发送消息，并期望同步得到结果。Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. 参数将使用结构化克隆算法进行序列化，就像window.postMessage一样，因此原型链将不包括在内。Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.发送Function、Promise、Symbol、WeakMap或WeakSet将抛出异常。

NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.发送诸如DOM对象或特殊Electron对象之类的非标准JavaScript类型将引发异常。

Since the main process does not have support for DOM objects such as ImageBitmap, File, DOMMatrix and so on, such objects cannot be sent over Electron's IPC to the main process, as the main process would have no way to decode them. 由于主进程不支持ImageBitmap、File、DOMMatrix等DOM对象，因此这些对象无法通过Electron的IPC发送到主进程，因为主进程无法对它们进行解码。Attempting to send such objects over IPC will result in an error.试图通过IPC发送此类对象将导致错误。

The main process handles it by listening for channel with ipcMain module, and replies by setting event.returnValue.主进程通过ipcMain模块监听channel进行处理，并通过设置event.returnValue进行回复。

⚠️ WARNING: Sending a synchronous message will block the whole renderer process until the reply is received, so use this method only as a last resort. ：发送同步消息将阻塞整个渲染器进程，直到收到回复，因此只能将此方法作为最后手段。It's much better to use the asynchronous version, invoke().使用异步版本invoke()要好得多。

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

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

Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.向主进程发送消息，可以选择转移零个或多个MessagePort对象的所有权。

The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.通过访问发出事件的ports属性，传输的MessagePort对象将作为MessagePortMain对象在主进程中可用。

For example:例如：

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

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

For more information on using MessagePort and MessageChannel, see the MDN documentation.有关使用MessagePort和MessageChannel的更多信息，请参阅MDN文档。

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

• webContentsId number
• channel string
• ...args any[]

Sends a message to a window with webContentsId via channel.通过channel向具有webContentsId的窗口发送消息。

ipcRenderer.sendToHost(channel, ...args)

• channel string
• ...args any[]

Like ipcRenderer.send but the event will be sent to the <webview> element in the host page instead of the main process.与ipcRenderer.send类似，但事件将被发送到主页面的<webview>元素，而不是主进程。

Event object事件对象

The documentation for the event object passed to the callback can be found in the ipc-renderer-event structure docs.传递给callback的event对象的文档可以在ipc-renderer-event结构文档中找到。