ipcMain
从主进程到渲染器进程异步通信。
¥Communicate asynchronously from the main process to renderer processes.
进程:主进程
¥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.
有关使用示例,请查看 工控机教程。
¥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
。¥When sending a message, the event name is the
channel
. -
要响应同步消息,需要设置
event.returnValue
。¥To reply to a synchronous message, you need to set
event.returnValue
. -
要将异步消息发送回发送者,可以使用
event.reply(...)
。此辅助方法将自动处理来自非主框架(例如 iframe)的消息,而event.sender.send(...)
将始终发送到主框架。¥To send an asynchronous message back to the sender, you can use
event.reply(...)
. This helper method will automatically handle messages coming from frames that aren't the main frame (e.g. iframes) whereasevent.sender.send(...)
will always send to the main frame.
方法
¥Methods
ipcMain
模块有以下方法来监听事件:
¥The ipcMain
module has the following method to listen for events:
ipcMain.on(channel, listener)
-
channel
字符串¥
channel
string -
listener
函数¥
listener
Function-
event
Ipc 主事件¥
event
IpcMainEvent -
...args
任何[]¥
...args
any[]
-
监听 channel
,当有新消息到达时,listener
将与 listener(event, args...)
一起调用。
¥Listens to channel
, when a new message arrives listener
would be called with
listener(event, args...)
.
ipcMain.once(channel, listener)
-
channel
字符串¥
channel
string -
listener
函数¥
listener
Function-
event
Ipc 主事件¥
event
IpcMainEvent -
...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.
ipcMain.removeListener(channel, listener)
-
channel
字符串¥
channel
string -
listener
函数¥
listener
Function-
...args
任何[]¥
...args
any[]
-
从指定 channel
的监听器数组中删除指定的 listener
。
¥Removes the specified listener
from the listener array for the specified
channel
.
ipcMain.removeAllListeners([channel])
-
channel
字符串(可选)¥
channel
string (optional)
删除指定 channel
的监听器。
¥Removes listeners of the specified channel
.
ipcMain.handle(channel, listener)
-
channel
字符串¥
channel
string -
listener
Function<Promise<any> | any>-
event
IpcMainInvoke 事件¥
event
IpcMainInvokeEvent -
...args
任何[]¥
...args
any[]
-
添加 invoke
able IPC 的处理程序。每当渲染器调用 ipcRenderer.invoke(channel, ...args)
时就会调用此处理程序。
¥Adds a handler for an invoke
able 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.
ipcMain.handle('my-invokable-ipc', async (event, ...args) => {
const result = await somePromise(...args)
return result
})
async () => {
const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)
// ...
}
作为第一个参数传递给处理程序的 event
与传递给常规事件监听器的 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
字符串¥
channel
string -
listener
Function<Promise<any> | any>-
event
IpcMainInvoke 事件¥
event
IpcMainInvokeEvent -
...args
任何[]¥
...args
any[]
-
处理单个 invoke
able IPC 消息,然后删除监听器。参见 ipcMain.handle(channel, listener)
。
¥Handles a single invoke
able IPC message, then removes the listener. See
ipcMain.handle(channel, listener)
.
ipcMain.removeHandler(channel)
-
channel
字符串¥
channel
string
删除 channel
的任何处理程序(如果存在)。
¥Removes any handler for channel
, if present.