Skip to main content

ipcMain

Comunica de forma assíncrona o processo principal aos processos de renderização.

Processo: Main

O módulo ipcMain é um emissor de eventos. Quando usado no processo principal, ele lida com mensagens assíncronas e síncronas enviadas a partir de um processo de renderização (página da web). As mensagens enviadas de um renderizador serão emitidas para este módulo.

Enviando Mensagens

Também é possível enviar mensagens do processo principal para o processo de renderização, veja webContents.send para obter mais informações.

  • Ao enviar uma mensagem, o nome do evento é o channel.
  • Para responder a uma mensagem síncrona, você precisa de configurar event.returnValue.
  • Para enviar uma mensagem assíncrona de volta para o remetente, você pode usar event.reply(...). This helper method will automatically handle messages coming from frames that aren't the main frame (e.g. iframes) whereas event.sender.send(...) will always send to the main frame.

Um exemplo de enviar e manipular mensagens entre os processos de renderização e principais:

// In main process.
const { ipcMain } = require('electron')
ipcMain.on('asynchronous-message', (event, arg) => {
console.log(arg) // prints "ping"
event.reply('asynchronous-reply', 'pong')
})

ipcMain.on('synchronous-message', (event, arg) => {
console.log(arg) // prints "ping"
event.returnValue = 'pong'
})
// In renderer process (web page).
// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.
// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.
const { ipcRenderer } = require('electron')
console.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints "pong"

ipcRenderer.on('asynchronous-reply', (event, arg) => {
console.log(arg) // prints "pong"
})
ipcRenderer.send('asynchronous-message', 'ping')

Métodos

O módulo ipcMain possui o seguinte método para ouvir eventos:

ipcMain.on(channel, listener)

  • channel String
  • listener Função
    • event IpcMainEvent
    • ...args any[]

Ouve o channel, quando uma mensagem chega, o listener deve ser chamado com listener(event, args...).

ipcMain.once(channel, listener)

  • channel String
  • listener Função
    • event IpcMainEvent
    • ...args any[]

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 String
  • listener Função
    • ...args any[]

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

ipcMain.removeAllListeners([channel])

  • channel String (opcional)

Removes listeners of the specified channel.

ipcMain.handle(channel, listener)

  • channel String
  • listener Function<Promise\<void> | any>
    • event IpcMainInvokeEvent
    • ...args any[]

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

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

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.

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 String
  • listener Function<Promise\<void> | any>
    • event IpcMainInvokeEvent
    • ...args any[]

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

ipcMain.removeHandler(channel)

  • channel String

Removes any handler for channel, if present.

IpcMainEvent object

The documentation for the event object passed to the callback can be found in the ipc-main-event structure docs.

IpcMainInvokeEvent object

The documentation for the event object passed to handle callbacks can be found in the ipc-main-invoke-event structure docs.