Skip to main content

ipcMain

从主进程向渲染进程进行异步通信。

进程：主进程

🌐 Process: Main

ipcMain 模块是一个 事件触发器。当在主进程中使用时，它处理从渲染进程（网页）发送的异步和同步消息。从渲染进程发送的消息将会触发到此模块。

🌐 The ipcMain module is an Event Emitter. When used in the main process, it handles asynchronous and synchronous messages sent from a renderer process (web page). Messages sent from a renderer will be emitted to this module.

有关使用示例，请查看 IPC 教程。

🌐 For usage examples, check out the IPC tutorial.

发送消息​

🌐 Sending messages

也可以从主进程向渲染进程发送消息，更多信息请参见 webContents.send。

🌐 It is also possible to send messages from the main process to the renderer process, see webContents.send for more information.

  • 发送消息时，事件名称是 channel。
  • 要回复同步消息，你需要设置 event.returnValue。
  • 要异步向发送者发送消息，你可以使用 event.reply(...)。这个辅助方法会自动处理来自非主框架（例如 iframe）的消息，而 event.sender.send(...) 总是会发送到主框架。

方法​

🌐 Methods

ipcMain 模块具有以下用于监听事件的方法：

🌐 The ipcMain module has the following methods to listen for events:

ipcMain.on(channel, listener)​

  • channel 字符串
  • listener 函数

监听 channel，当有新消息到达时，listener 会被调用，并传入 listener(event, args...)。

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

ipcMain.off(channel, listener)​

  • channel 字符串
  • listener 函数

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

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

ipcMain.once(channel, listener)​

  • channel 字符串
  • listener 函数

为该事件添加一次性的 listener 函数。这个 listener 只会在下一次向 channel 发送消息时被调用，之后它将被移除。

🌐 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.

ipcMain.addListener(channel, listener)​

  • channel 字符串
  • listener 函数

[ipcMain.on](#ipcmainonchannel-listener) 的别名。

🌐 Alias for ipcMain.on.

ipcMain.removeListener(channel, listener)​

  • channel 字符串
  • listener 函数
    • ...args any[]

[ipcMain.off](#ipcmainoffchannel-listener) 的别名。

🌐 Alias for ipcMain.off.

ipcMain.removeAllListeners([channel])​

  • channel 字符串（可选）

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

🌐 Removes all listeners from the specified channel. Removes all listeners from all channels if no channel is specified.

ipcMain.handle(channel, listener)​

  • channel 字符串
  • 'listener' 函数<Promise<any> | 任何>

为可 invoke 的 IPC 添加一个处理程序。每当渲染器调用 ipcRenderer.invoke(channel, ...args) 时，将调用此处理程序。

🌐 Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, ...args).

如果 listener 返回一个 Promise，该 Promise 的最终结果将作为对远程调用者的回复返回。否则，监听器的返回值将被用作回复的值。

🌐 If listener returns a Promise, the eventual result of the promise will be returned as a reply to the remote caller. Otherwise, the return value of the listener will be used as the value of the reply.

Main Process
ipcMain.handle('my-invokable-ipc', async (event, ...args) => {
  const result = await somePromise(...args)
  return result
})
Renderer Process
async () => {
  const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)
  // ...
}

传递给处理程序作为第一个参数的 event 与传递给常规事件监听器的参数相同。它包含有关哪个 WebContents 是调用请求来源的信息。

🌐 The event that is passed as the first argument to the handler is the same as that passed to a regular event listener. It includes information about which WebContents is the source of the invoke request.

通过主进程中的 handle 抛出的错误并不透明，因为它们被序列化，并且只将原始错误的 message 属性提供给渲染进程。详情请参阅 #24427。

🌐 Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details.

ipcMain.handleOnce(channel, listener)​

  • channel 字符串
  • 'listener' 函数<Promise<any> | 任何>

处理单个 invoke 可用的 IPC 消息，然后移除监听器。参见 ipcMain.handle(channel, listener)。

🌐 Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener).

ipcMain.removeHandler(channel)​

  • channel 字符串

如果存在，移除 channel 的任何处理程序。

🌐 Removes any handler for channel, if present.