ipcRenderer

歷史記錄

版本	變更
>=29.0.0	ipcRenderer 無法再透過 contextBridge 傳送

從渲染器程序非同步地與主程序通訊。

程序：渲染器

ipcRenderer 模組是一個 EventEmitter。 它提供了一些方法，讓您可以從渲染程序（網頁）向主程序發送同步和非同步訊息。 您也可以接收來自主程序的回覆。

請參閱 IPC 教學 以取得程式碼範例。

方法

ipcRenderer 模組具有以下方法來監聽事件和發送訊息

ipcRenderer.on(channel, listener)

• channel 字串
• listener 函數
  • 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 字串
• listener 函數
  • event IpcRendererEvent
  • ...args any[]

從指定 channel 的監聽器陣列中移除指定的 listener。

ipcRenderer.once(channel, listener)

• channel 字串
• listener 函數
  • event IpcRendererEvent
  • ...args any[]

為事件新增一次性的 listener 函數。 此 listener 僅在下次向 channel 發送訊息時調用，之後便會移除。

ipcRenderer.addListener(channel, listener)

• channel 字串
• listener 函數
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.on 的別名。

ipcRenderer.removeListener(channel, listener)

• channel 字串
• listener 函數
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.off 的別名。

ipcRenderer.removeAllListeners([channel])

• channel 字串 (選用)

從指定的 channel 移除所有監聽器。 如果未指定頻道，則從所有頻道移除所有監聽器。

ipcRenderer.send(channel, ...args)

• channel 字串
• ...args any[]

透過 channel 向主程序發送非同步訊息，以及引數。 引數將使用 結構化複製演算法序列化，就像 window.postMessage 一樣，因此不會包含原型鏈。 發送函數、Promise、Symbol、WeakMap 或 WeakSet 將會拋出例外。

注意： 發送非標準 JavaScript 類型，例如 DOM 物件或特殊的 Electron 物件，將會拋出例外。

由於主程序不支援 DOM 物件，例如 ImageBitmap、File、DOMMatrix 等，因此這些物件無法透過 Electron 的 IPC 發送到主程序，因為主程序將無法解碼它們。 嘗試透過 IPC 發送此類物件將會導致錯誤。

主程序透過使用 ipcMain 模組監聽 channel 來處理它。

如果您需要將 MessagePort 傳輸到主程序，請使用 ipcRenderer.postMessage。

如果您想要從主程序接收單一回應，例如方法呼叫的結果，請考慮使用 ipcRenderer.invoke。

ipcRenderer.invoke(channel, ...args)

• channel 字串
• ...args any[]

傳回 Promise<any> - 以來自主程序的回應解析。

透過 channel 向主程序發送訊息，並非同步地預期結果。 引數將使用 結構化複製演算法序列化，就像 window.postMessage 一樣，因此不會包含原型鏈。 發送函數、Promise、Symbol、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。

注意 發送非標準 JavaScript 類型，例如 DOM 物件或特殊的 Electron 物件，將會拋出例外。

由於主程序不支援 DOM 物件，例如 ImageBitmap、File、DOMMatrix 等，因此這些物件無法透過 Electron 的 IPC 發送到主程序，因為主程序將無法解碼它們。 嘗試透過 IPC 發送此類物件將會導致錯誤。

注意 如果主程序中的處理常式拋出錯誤，則 invoke 傳回的 promise 將會拒絕。 然而，渲染器程序中的 Error 物件將與主程序中拋出的物件不同。

ipcRenderer.sendSync(channel, ...args)

• channel 字串
• ...args any[]

傳回 any - 由 ipcMain 處理常式傳回的值。

透過 channel 向主程序發送訊息，並同步地預期結果。 引數將使用 結構化複製演算法序列化，就像 window.postMessage 一樣，因此不會包含原型鏈。 發送函數、Promise、Symbol、WeakMap 或 WeakSet 將會拋出例外。

注意： 發送非標準 JavaScript 類型，例如 DOM 物件或特殊的 Electron 物件，將會拋出例外。

由於主程序不支援 DOM 物件，例如 ImageBitmap、File、DOMMatrix 等，因此這些物件無法透過 Electron 的 IPC 發送到主程序，因為主程序將無法解碼它們。 嘗試透過 IPC 發送此類物件將會導致錯誤。

主程序透過使用 ipcMain 模組監聽 channel 來處理它，並透過設定 event.returnValue 來回覆。

⚠️ 警告： 發送同步訊息將會封鎖整個渲染器程序，直到收到回覆為止，因此僅在萬不得已時才使用此方法。 最好使用非同步版本 invoke()。

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

• channel 字串
• message any
• transfer MessagePort[] (選用)

向主程序發送訊息，可選擇性地轉移零或多個 MessagePort 物件的所有權。

轉移的 MessagePort 物件將在主程序中以 MessagePortMain 物件的形式提供，透過存取發射事件的 ports 屬性即可取得。

例如

// 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> 元素，而不是主程序。