ipcRenderer

History

Version(s)	Changes
None	ipcRenderer can no longer be sent over the contextBridge

Communication asynchrone d'un processus de rendu vers le processus principal.

Process: Renderer

Le module ipcRender est un EventEmitter. Il fournit quelques méthodes permettant d'envoyer des messages synchrones et asynchrones au processus principal depuis le processus de rendu (page web). Vous pouvez également recevoir des réponses du processus principal.

See IPC tutorial for code examples.

Méthodes

Le module de ipcRenderer possède les méthodes suivantes pour écouter les événements et envoyer des messages :

ipcRenderer.on(channel, listener)

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

Ecoute sur channel et listener sera appelé ainsi: listener(event, args...) à la réception d'un nouveau message .

avertissement

Do not expose the event argument to the renderer for security reasons! Wrap any callback that you receive from the renderer in another function like this: ipcRenderer.on('my-channel', (event, ...args) => callback(...args)). Not wrapping the callback in such a function would expose dangerous Electron APIs to the renderer process. See the security guide for more info.

ipcRenderer.off(channel, listener)

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

Supprime du tableau d'écouteurs le listener spécifié pour le channel spécifié.

ipcRenderer.once(channel, listener)

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

Ajoute un listener à déclenchement unique pour l’événement. Ce listener sera appelé uniquement lors de la prochaine émission d'un message sur le channel, après quoi il sera supprimé.

ipcRenderer.addListener(channel, listener)

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

Alias for ipcRenderer.on.

ipcRenderer.removeListener(channel, listener)

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

Alias for ipcRenderer.off.

ipcRenderer.removeAllListeners([channel])

• channel string (facultatif)

Supprime tous les écouteurs du channel spécifié. Supprime tous les écouteurs de tous les canaux si aucun canal n'est spécifié.

ipcRenderer.send(channel, ...args)

• channel string
• ...args any[]

Envoie un message asynchrone ainsi que des arguments au processus principal via channel. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. L’envoi de fonctions, de promesses, de symboles, de WeakMaps ou de WeakSets lèvera une exception.

NOTE: L'envoi de types Javascript non standards tels que des objets DOM ou des objets spéciaux Electron est déprécié, et déclenchera une exception à partir d'Electron 9.

Le processus principal ne prenant pas en charge les objets DOM tels que ImageBitmap, File, DOMMatrix et ainsi de suite, de tels objets ne pourront pas être envoyés au processus principal par l'IPC d'Electron, car celui-ci n'a aucun moyen de les décoder . Toute tentative d’envoi de tels objets via IPC entraînera une erreur.

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

Si vous avez besoin de transférer un MessagePort au processus principal, utilisez ipcRenderer.postMessage.

Si vous souhaitez recevoir une réponse unique du processus principal, comme le résultat d’un appel de méthode, envisagez d’utiliser plutôt ipcRenderer.invoke.

ipcRenderer.invoke(channel, ...args)

• channel string
• ...args any[]

Retourne une Promise<any> - qui se résout avec la réponse du processus principal.

Envoie un message au processus principal via channel et attend un résultat asynchrone. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. L’envoi de fonctions, de promesses, de symboles, de WeakMaps ou de WeakSets lèvera une exception.

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

Par exemple :

// Processus de rendu
ipcRenderer.invoke('some-name', someArgument).then((result) => {
  // ...
})

// Processus principal
ipcMain.handle('some-name', async (event, someArgument) => {
  const result = wait doSomeWork(someArgument)
  return result
})

Si vous avez besoin de transférer un MessagePort au processus principal, utilisez ipcRenderer.postMessage.

Si vous n’attendez pas de réponse au message, envisagez d’utiliser ipcRenderer.send.

[!NOTE] Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.

Le processus principal ne prenant pas en charge les objets DOM tels que ImageBitmap, File, DOMMatrix et ainsi de suite, de tels objets ne pourront pas être envoyés au processus principal par l'IPC d'Electron, car celui-ci n'a aucun moyen de les décoder . Toute tentative d’envoi de tels objets via IPC entraînera une erreur.

[!NOTE] If the handler in the main process throws an error, the promise returned by invoke will reject. Cependant, l'objet Error dans le processus de rendu ne sera pas le même que celui lancé dans le processus principal.

ipcRenderer.sendSync(canal, ...args)

• channel string
• ...args any[]

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

Envoie un message au processus principal de manière asynchrone via channel et attend un résultat asynchrone. Arguments will be serialized with the Structured Clone Algorithm, just like window.postMessage, so prototype chains will not be included. L’envoi de fonctions, de promesses, de symboles, de WeakMaps ou de WeakSets lèvera une exception.

NOTE: L'envoi de types Javascript non standards tels que des objets DOM ou des objets spéciaux Electron est déprécié, et déclenchera une exception à partir d'Electron 9.

Le processus principal ne prenant pas en charge les objets DOM tels que ImageBitmap, File, DOMMatrix et ainsi de suite, de tels objets ne pourront pas être envoyés au processus principal par l'IPC d'Electron, car celui-ci n'a aucun moyen de les décoder . Toute tentative d’envoi de tels objets via IPC entraînera une erreur.

The main process handles it by listening for channel with ipcMain module, and replies by setting 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().

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

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

Envoie un message au processus principal, en transférant éventuellement la détention d'objets MessagePort .

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

Par exemple :

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

ipcRenderer.sendToHost(canal, ...args)

• channel string
• ...args any[]

Comme ipcRenderer.send, mais l'événement sera envoyé à l'élément <webview> dans la page hôte au lieu du processus main.