ipcRenderer

歷史

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

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

程序：渲染器

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

如需程式碼範例，請參閱 IPC 教學。

方法

ipcRenderer 模組有以下方法可以監聽事件和傳送訊息

ipcRenderer.on(channel, listener)

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

監聽 channel，當新訊息送達時，將會使用 listener(event, args...) 呼叫 listener。

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 中移除所有監聽器。如果沒有指定 channel，則從所有 channel 中移除所有監聽器。

ipcRenderer.send(channel, ...args)

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

透過 channel 向主程序傳送非同步訊息，以及引數。引數將使用 結構化複製演算法進行序列化，就像 window.postMessage 一樣，因此不會包含原型鏈。傳送函數、Promise、符號、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、符號、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、符號、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> 元素，而不是主程序。