跳转至

ipcRenderer

从指定 channel 的监听器数组中移除指定的 listener。

ipcRenderer.once(channel, listener)

为事件添加一个一次性 listener 函数。此 listener 仅在下一次向 channel 发送消息时被调用，之后会被移除。

ipcRenderer.addListener(channel, listener)

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

返回 Promise<any> - 以主进程的响应作为解析值。

通过 channel 向主进程发送消息，并异步期望一个结果。参数将使用 结构化克隆算法 进行序列化，就像 [window.postMessage][] 一样，因此原型链不会被包含。发送函数、Promise、Symbol、WeakMap 或 WeakSet 会抛出异常。

主进程应使用 ipcMain.handle() 监听 channel。

例如：

```js @ts-type={someArgument:unknown} @ts-type={doSomeWork:(arg:unknown)=>Promise} // 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`](#ipcrendererpostmessagechannel-message-transfer)。

如果不需要对消息进行响应，请考虑使用 [`ipcRenderer.send`](#ipcrenderersendchannel-args)。

> [!NOTE]
> 发送非标准 JavaScript 类型（例如 DOM 对象或特殊的 Electron 对象）会抛出异常。
>
> 由于主进程不支持 `ImageBitmap`、`File`、`DOMMatrix` 等 DOM 对象，因此无法通过 Electron 的 IPC 将这些对象发送到主进程，因为主进程无法解码它们。尝试通过 IPC 发送此类对象会导致错误。



> [!NOTE]
> 如果主进程中的处理函数抛出错误，
> `invoke` 返回的 Promise 将被拒绝。
> 但是，渲染进程中的 `Error` 对象
> 与主进程中抛出的对象并不相同。

### `ipcRenderer.sendSync(channel, ...args)` {#ipcrenderersendsynchannel-args}

* `channel` string
* `...args` any[]

返回 `any` - 由 [`ipcMain`](ipc-main.md) 处理函数返回的值。

通过 `channel` 向主进程发送消息，并同步等待结果。参数会使用 [结构化克隆算法][SCA] 进行序列化，
与 [`window.postMessage`][] 一样，因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 会抛出异常。

> **注意：** 发送非标准 JavaScript 类型（例如 DOM 对象或
> 特殊的 Electron 对象）会抛出异常。
>
> 由于主进程不支持 `ImageBitmap`、`File`、`DOMMatrix` 等 DOM 对象，
> 因此无法通过 Electron 的 IPC 将这些对象发送到主进程，因为主进程没有方式解码
> 它们。尝试通过 IPC 发送此类对象会导致错误。

主进程通过 [`ipcMain`](ipc-main.md) 模块监听 `channel` 来处理它，
并通过设置 `event.returnValue` 进行回复。

> [!WARNING]
> 发送同步消息会阻塞整个
> 渲染进程，直到收到回复，因此请仅将此方法作为
> 最后手段使用。最好使用异步版本，
> [`invoke()`](ipc-renderer.md#ipcrendererinvokechannel-args).

### `ipcRenderer.postMessage(channel, message, [transfer])` {#ipcrendererpostmessagechannel-message-transfer}

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22404
-->

  • channel string
  • message any
  • transfer MessagePort[] (可选)

向主进程发送消息，可选择转移零个或多个 [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 string
  • ...args any[]

与 ipcRenderer.send 类似，但事件将发送到宿主页面中的 <webview> 元素， 而不是主进程。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron