Aller au contenu principal

ipcRenderer

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

Processus : 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.

Consultez la doc sur la communicatioçn inter-processus pour obtenir des exemples de code.

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
    • événement IpcRendererEvent
    • ...args any[]

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

ipcRenderer.once(channel, listener)​

  • channel string
  • listener Function
    • événement 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.removeListener(channel, listener)​

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

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

ipcRenderer.removeAllListeners(channel)​

  • channel string

Supprime tous les écouteurs, ou ceux du channel spécifié.

ipcRenderer.send(channel, ...args)​

  • channel string
  • ...args any[]

Envoie un message asynchrone ainsi que des arguments au processus principal via channel. Les arguments seront sérialisés avec le Structured Clone Algorithm, tout comme window.postMessage, de sorte que les chaînes prototypes ne seront pas incluses. 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.

Le processus principal écoute ces messages sur le canal fournit par channel à l'aide du module ipcMain.

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. Les arguments seront sérialisés avec le Structured Clone Algorithm, tout comme window.postMessage, de sorte que les chaînes prototypes ne seront pas incluses. L’envoi de fonctions, de promesses, de symboles, de WeakMaps ou de WeakSets lèvera une exception.

Le processus principal devra écouter sur channel avec 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: L'envoi de types Javascript non standards tels que des objets DOM ou des objets spécifiques à Electron déclenchera une 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 Si dans le processus principal, le gestionnaire lance une erreur, la promesse retournée par invoke sera rejetée. 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[]

Retourne any - La valeur renvoyé par l'écouteur du ipcMain.

Envoie un message au processus principal de manière asynchrone via channel et attend un résultat asynchrone. Les arguments seront sérialisés avec le Structured Clone Algorithm, tout comme window.postMessage, de sorte que les chaînes prototypes ne seront pas incluses. 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.

Le processus principal le gère en écoutant le canal avec le module ipcMain , et répond en définissant event.returnValue.

⚠️ AVERTISSEMENT: L’envoi d’un message synchrone bloquera l’ensemble du processus de rendu jusqu’à ce que la réponse soit reçue, vous ne devez donc utiliser cette méthode qu'en dernier recours . Il est de loin préférable d’utiliser la version asynchrone, 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 .

Les objets MessagePort transférés seront disponibles dans le processus principal en tant qu’objets MessagePortMain en accédant à la propriété ports de l’événement émis.

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

Pour plus d’informations sur l’utilisation de MessagePort et de MessageChannel, consultez la documentation MDN .

ipcRenderer.sendTo(webContentsId, channel, ...args)​

  • webContentsId number
  • channel string
  • ...args any[]

Envoie un message à une fenêtre avec webContentsId via canal.

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.

Objet event​

La documentation de l'objet événement passé à la callback peut être trouvée dans la documentation de la structure ipc-renderer-event.