ipcRenderer

History

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

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

Process: Renderer

[!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.

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

See IPC tutorial for code examples.

メソッド

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

ipcRenderer.on(channel, listener)

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

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

警告

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[]

指定した 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 (任意)

Removes all listeners from the specified channel. Removes all listeners from all channels if no channel is specified.

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 経由でこのようなオブジェクトを送信するとエラーになります。

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

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

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

ipcRenderer.invoke(channel, ...args)

• channel string
• ...args any[]

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

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

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

以下がその例です。

// レンダラープロセス
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] Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.

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

[!NOTE] If the handler in the main process throws an error, the promise returned by invoke will reject. ただし、レンダラープロセスの Error オブジェクト はメインプロセスでのものと異なります。

ipcRenderer.sendSync(channel, ...args)

• channel string
• ...args any[]

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

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

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

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

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[] (任意)

メッセージをメインプロセスに送信し、任意でゼロ個以上の 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> に送信されます。