ipcRenderer

ipcRenderer

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

¥Communicate asynchronously from a renderer process to the main process.

进程：渲染器

¥Process: Renderer

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

¥The ipcRenderer module is an 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.

方法

¥Methods

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

¥The ipcRenderer module has the following method to listen for events and send messages:

ipcRenderer.on(channel, listener)

• channel 字符串

  ¥channel string

• listener 函数

  ¥listener Function

  • event Ipc 渲染事件

    ¥event IpcRendererEvent

  • ...args 任何[]

    ¥...args any[]

监听 channel，当有新消息到达时，listener 将与 listener(event, args...) 一起调用。

¥Listens to channel, when a new message arrives listener would be called with listener(event, args...).

ipcRenderer.off(channel, listener)

• channel 字符串

  ¥channel string

• listener 函数

  ¥listener Function

  • event Ipc 渲染事件

    ¥event IpcRendererEvent

  • ...args 任何[]

    ¥...args any[]

ipcRenderer.removeListener 的别名。

¥Alias for ipcRenderer.removeListener.

ipcRenderer.once(channel, listener)

• channel 字符串

  ¥channel string

• listener 函数

  ¥listener Function

  • event Ipc 渲染事件

    ¥event IpcRendererEvent

  • ...args 任何[]

    ¥...args any[]

为该事件添加一次性 listener 功能。仅当下次将消息发送到 channel 时才会调用此 listener，之后将其删除。

¥Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.

ipcRenderer.addListener(channel, listener)

• channel 字符串

  ¥channel string

• listener 函数

  ¥listener Function

  • event Ipc 渲染事件

    ¥event IpcRendererEvent

  • ...args 任何[]

    ¥...args any[]

ipcRenderer.on 的别名。

¥Alias for ipcRenderer.on.

ipcRenderer.removeListener(channel, listener)

• channel 字符串

  ¥channel string

• listener 函数

  ¥listener Function

  • event Ipc 渲染事件

    ¥event IpcRendererEvent

  • ...args 任何[]

    ¥...args any[]

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

¥Removes the specified listener from the listener array for the specified channel.

ipcRenderer.removeAllListeners(channel)

• channel 字符串

  ¥channel string

删除所有监听器或指定 channel 的监听器。

¥Removes all listeners, or those of the specified channel.

ipcRenderer.send(channel, ...args)

• channel 字符串

  ¥channel string

• ...args 任何[]

  ¥...args any[]

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

¥Send an asynchronous message to the main process via channel, along with arguments. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.

注意：发送非标准 JavaScript 类型（例如 DOM 对象或特殊 Electron 对象）将引发异常。

¥NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.

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

¥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. Attempting to send such objects over IPC will result in an error.

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

¥The main process handles it by listening for channel with the ipcMain module.

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

¥If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.

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

¥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(channel, ...args)

• channel 字符串

  ¥channel string

• ...args 任何[]

  ¥...args any[]

返回 Promise<any> - 通过主进程的响应来解决。

¥Returns Promise<any> - Resolves with the response from the main process.

通过 channel 向主进程发送消息并异步期待结果。参数将与 结构化克隆算法 一起序列化，就像 window.postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbols、WeakMap 或 WeakSet 将引发异常。

¥Send a message to the main process via channel and expect a result asynchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.

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

¥The main process should listen for channel with ipcMain.handle().

例如：

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

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

¥If you need to transfer a MessagePort to the main process, use ipcRenderer.postMessage.

如果你不需要对该消息进行响应，请考虑使用 ipcRenderer.send。

¥If you do not need a response to the message, consider using ipcRenderer.send.

注意 发送非标准 JavaScript 类型（例如 DOM 对象或特殊 Electron 对象）将引发异常。

¥Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.

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

¥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. Attempting to send such objects over IPC will result in an error.

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

¥If the handler in the main process throws an error, the promise returned by invoke will reject. However, the Error object in the renderer process will not be the same as the one thrown in the main process.

ipcRenderer.sendSync(channel, ...args)

• channel 字符串

  ¥channel string

• ...args 任何[]

  ¥...args any[]

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

¥Returns any - The value sent back by the ipcMain handler.

通过 channel 向主进程发送消息并同步期待结果。参数将与 结构化克隆算法 一起序列化，就像 window.postMessage 一样，因此不会包含原型链。发送函数、Promise、Symbols、WeakMap 或 WeakSet 将引发异常。

¥Send a message to the main process via channel and expect a result synchronously. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.

注意：发送非标准 JavaScript 类型（例如 DOM 对象或特殊 Electron 对象）将引发异常。

¥NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.

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

¥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. Attempting to send such objects over IPC will result in an error.

主进程通过用 ipcMain 模块监听 channel 来处理，并通过设置 event.returnValue 来响应。

¥The main process handles it by listening for channel with ipcMain module, and replies by setting event.returnValue.

⚠️WARNING:发送同步消息将阻塞整个渲染器进程，直到收到响应，因此仅将此方法用作最后的手段。使用异步版本 invoke() 要好得多。

¥⚠️ 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().

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

• channel 字符串

  ¥channel string

• message 任意

  ¥message any

• transfer 消息端口[]（可选）

  ¥transfer MessagePort[] (optional)

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

¥Send a message to the main process, optionally transferring ownership of zero or more MessagePort objects.

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

¥The transferred MessagePort objects will be available in the main process as MessagePortMain objects by accessing the ports property of the emitted event.

例如：

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

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

¥For more information on using MessagePort and MessageChannel, see the MDN documentation.

ipcRenderer.sendToHost(channel, ...args)

• channel 字符串

  ¥channel string

• ...args 任何[]

  ¥...args any[]

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

¥Like ipcRenderer.send but the event will be sent to the <webview> element in the host page instead of the main process.