メインコンテンツへスキップ

ipcRenderer

履歴

レンダラープロセスからメインプロセスに非同期通信を行います。

プロセス: レンダラー

ipcRendererモジュールはEventEmitterです。レンダラープロセス（ウェブページ）からメインプロセスに同期および非同期メッセージを送信するためのいくつかのメソッドを提供します。メインプロセスから応答を受信することもできます。

コードの例については ipc チュートリアルを参照してください。

メソッド​

ipcRendererモジュールには、イベントに応答しメッセージを送信するための次のメソッドがあります。

ipcRenderer.on(channel, listener)​

channelをリッスンし、新しいメッセージが届くとlistenerがlistener(event, args...)で呼び出されます。

ipcRenderer.off(channel, listener)​

ipcRenderer.removeListenerのエイリアスです。

ipcRenderer.once(channel, listener)​

イベントに対して listener 関数を1回追加します。この listener は、channel にメッセージが送信されたときに1回だけ呼び出され、その後削除されます。

ipcRenderer.addListener(channel, listener)​

ipcRenderer.onの別名です。

ipcRenderer.removeListener(channel, listener)​

指定された channel のリスナ配列から、指定された listener を削除します。

ipcRenderer.removeAllListeners(channel)​

  • channel 文字列

すべてのリスナ、または指定された channel のリスナを削除します。

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

  • channel 文字列
  • ...args any[]

channel 経由でメインプロセスに非同期メッセージを送信します（引数あり）。 引数は 構造化されたクローンアルゴリズム でシリアル化されるため、window.postMessage と同様に、プロトタイプチェーンは含まれません。 関数、Promise、シンボル、WeakMap、またはWeakSetを送信すると、例外が発生します。

注意: DOMオブジェクトや特別なElectronオブジェクトなどの標準外のJavaScriptタイプを送信すると、例外が発生します。

メインプロセスは ImageBitmap、File、DOMMatrix などのDOMオブジェクトをサポートしていないため、このようなオブジェクトはElectronのIPCを介してメインプロセスに送信できません。メインプロセスにはそれらをデコードする方法がないからです。このようなオブジェクトをIPC経由で送信しようとすると、エラーが発生します。

メインプロセスは ipcMain モジュールで channel をリッスンして処理します。

MessagePort をメインプロセスに転送する必要がある場合は、ipcRenderer.postMessage を使用します。

メソッド呼び出しの結果など、メインプロセスから単一の応答を受信する必要がある場合は、ipcRenderer.invoke を使用することを検討してください。

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

  • channel 文字列
  • ...args any[]

Promise<any> を返します。メインプロセスからの応答で解決されます。

channel 経由でメインプロセスにメッセージを送信し、結果を非同期で取得します。 引数は 構造化されたクローンアルゴリズム でシリアル化されるため、window.postMessage と同様に、プロトタイプチェーンは含まれません。 関数、Promise、シンボル、WeakMap、またはWeakSetを送信すると、例外が発生します。

メインプロセスは ipcMain.handle() で channel をリッスンする必要があります。

たとえば

// Renderer process
ipcRenderer.invoke('some-name', someArgument).then((result) => {
  // ...
})

// Main process
ipcMain.handle('some-name', async (event, someArgument) => {
  const result = await doSomeWork(someArgument)
  return result
})

MessagePort をメインプロセスに転送する必要がある場合は、ipcRenderer.postMessage を使用します。

メッセージに対する応答が必要ない場合は、ipcRenderer.send を使用することを検討してください。

注意: DOMオブジェクトや特別なElectronオブジェクトなどの標準外のJavaScriptタイプを送信すると、例外が発生します。

メインプロセスは ImageBitmap、File、DOMMatrix などのDOMオブジェクトをサポートしていないため、このようなオブジェクトはElectronのIPCを介してメインプロセスに送信できません。メインプロセスにはそれらをデコードする方法がないからです。このようなオブジェクトをIPC経由で送信しようとすると、エラーが発生します。

注意: メインプロセスのハンドラでエラーが発生すると、invoke によって返されるpromiseが拒否されます。ただし、レンダラープロセスの Error オブジェクトは、メインプロセスでスローされたものと同じではありません。

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

  • channel 文字列
  • ...args any[]

anyを返します - ipcMainハンドラーから返された値。

channel経由でメインプロセスにメッセージを送信し、結果を同期的に待機します。引数は構造化されたクローンアルゴリズムを使用してシリアル化されます（window.postMessageと同様）。したがって、プロトタイプチェーンは含まれません。Function、Promise、Symbol、WeakMap、WeakSetを送信すると例外がスローされます。

注意: DOMオブジェクトや特別なElectronオブジェクトなどの標準外のJavaScriptタイプを送信すると、例外が発生します。

メインプロセスは ImageBitmap、File、DOMMatrix などのDOMオブジェクトをサポートしていないため、このようなオブジェクトはElectronのIPCを介してメインプロセスに送信できません。メインプロセスにはそれらをデコードする方法がないからです。このようなオブジェクトをIPC経由で送信しようとすると、エラーが発生します。

メインプロセスはipcMainモジュールでchannelをリッスンして処理し、event.returnValueを設定することで応答します。

⚠️ 警告: 同期メッセージを送信すると応答が受信されるまでレンダラープロセス全体がブロックされるので、このメソッドは最後の手段としてのみ使用してください。非同期バージョンのinvoke()を使用する方がはるかに適切です。

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

  • channel 文字列
  • message any
  • transfer MessagePort[]（任意）

メインプロセスにメッセージを送信します。オプションで、0個以上のMessagePortオブジェクトの所有権を転送します。

転送されたMessagePortオブジェクトは、生成されたイベントのportsプロパティにアクセスすることで、メインプロセスでMessagePortMainオブジェクトとして利用できます。

たとえば

// Renderer process
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])

// Main process
ipcMain.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

MessagePortとMessageChannelの使用の詳細については、MDNのドキュメントを参照してください。

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

  • channel 文字列
  • ...args any[]

ipcRenderer.sendのようですが、イベントはメインプロセスではなくホストページの<webview>要素に送信されます。