ipcRenderer

History

Version(s)	Changes
None	ipcRenderer は contextBridge を越えて送れないようになりました

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

プロセス: レンダラー

[!IMPORTANT] コンテキスト分離を有効にしてレンダラープロセスからこの API を呼び出す場合は、プリロードスクリプトに API 呼び出しを記述し、contextBridge API でその API 呼び出しを 公開 します。

ipcRenderer モジュールは Event Emitter を継承しています。 レンダラープロセス (ウェブページ) からメインプロセスに同期及び非同期メッセージを送れるように、いくつかのメソッドを提供します。 メインプロセスからの返信を受け取ることもできます。

コードサンプルは IPC チュートリアル をご参照ください。

メソッド

ipcRenderer オブジェクトは、イベントを受け取り、送るために以下のメソッドがあります。

ipcRenderer.on(channel, listener)

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

channel に新しいメッセージが来たときに listener が listener(event, args...) として呼ばれます、

警告

セキュリティ上の理由から、event 引数をレンダラーへ公開しないでください！ レンダラーから受け取るコールバックは、ipcRenderer.on('my-channel', (event, ...args) => callback(...args)) のように別の関数でラップしてください。 このような関数でコールバックをラップしないと、危険な Electron API がレンダラープロセスへ公開されてしまいます。 詳細は セキュリティガイド をご覧ください。

ipcRenderer.off(channel, listener)

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

指定した channel の listener 配列から、指定した listener を削除します。

ipcRenderer.once(channel, listener)

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

イベントに対する一回限りの listener 関数を追加します。 この listener は、次にメッセージが channel へ送信されたときに、削除されてから呼び出されます。

ipcRenderer.addListener(channel, listener)

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

ipcRenderer.on の別名です。

ipcRenderer.removeListener(channel, listener)

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

ipcRenderer.off の別名です。

ipcRenderer.removeAllListeners([channel])

• channel string (任意)

指定した channel のリスナーを全て削除します。 チャンネルが指定されていない場合、すべてのチャンネルのすべてのリスナーを削除します。

ipcRenderer.send(channel, ...args)

• channel string
• ...args any[]

引数と共に、channel を介してメインプロセスに非同期メッセージを送信します。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

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

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

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

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

メソッド呼び出しの結果のようにメインプロセスから応答を一つだけ受け取りたい場合は、ipcRenderer.invoke の使用を検討してください。

ipcRenderer.invoke(channel, ...args)

• channel string
• ...args any[]

戻り値 Promise<any> - メインプロセスからの応答で解決します。

channel を介して非同期でメインプロセスにメッセージを送信し、結果を待ちます。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

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

以下がその例です。

// レンダラープロセス
ipcRenderer.invoke('some-name', someArgument).then((result) => {
  // ...
})

// メインプロセス
ipcMain.handle('some-name', async (event, someArgument) => {
  const result = await doSomeWork(someArgument)
  return result
})

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

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

[!NOTE] DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。

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

[!NOTE] メインプロセスのハンドラがエラーを送出すると、invoke が返す Promise は拒否されます。 ただし、レンダラープロセスの Error オブジェクト はメインプロセスでのものと異なります。

ipcRenderer.sendSync(channel, ...args)

• channel string
• ...args any[]

戻り値 any - ipcMain ハンドラから返された値。

channel を介して同期でメインプロセスにメッセージを送信し、結果を待ちます。 引数は window.postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

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

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

メインプロセスは ipcMain オブジェクトで channel をリッスンしてそれを処理します。そして event.returnValue をセットすることで応答します。

[!WARNING] 同期メッセージを送信すると、応答を受信するまでレンダラープロセス全体がブロックされます。そのため、このメソッドは最終手段として使用してください。 非同期バージョンの、invoke() を使用することを推奨します。

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

• channel string
• message any
• transfer MessagePort[] (任意)

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

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

以下がその例です。

// レンダラープロセス
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])

// メインプロセス
ipcMain.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

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

ipcRenderer.sendToHost(channel, ...args)

• channel string
• ...args any[]

ipcRenderer.send に似ていますが、イベントはメインプロセスの代わりにホストページの <webview> に送信されます。