2fad53e66b
* refactor: use v8 serialization for ipc * cloning process.env doesn't work * serialize host objects by enumerating key/values * new serialization can handle NaN, Infinity, and undefined correctly * can't allocate v8 objects during GC * backport microtasks fix * fix compile * fix node_stream_loader reentrancy * update subframe spec to expect undefined instead of null * write undefined instead of crashing when serializing host objects * fix webview spec * fix download spec * buffers are transformed into uint8arrays * can't serialize promises * fix chrome.i18n.getMessage * fix devtools tests * fix zoom test * fix debug build * fix lint * update ipcRenderer tests * fix printToPDF test * update patch * remove accidentally re-added remote-side spec * wip * don't attempt to serialize host objects * jump through different hoops to set options.webContents sometimes * whoops * fix lint * clean up error-handling logic * fix memory leak * fix lint * convert host objects using old base::Value serialization * fix lint more * fall back to base::Value-based serialization * remove commented-out code * add docs to breaking-changes.md * Update breaking-changes.md * update ipcRenderer and WebContents docs * lint * use named values for format tag * save a memcpy for ~30% speedup * get rid of calls to ShallowClone * extra debugging for paranoia * d'oh, use the correct named tags * apparently msstl doesn't like this DCHECK * funny story about that DCHECK * disable remote-related functions when enable_remote_module = false * nits * use EnableIf to disable remote methods in mojom * fix include * review comments
153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# ipcRenderer
|
|
|
|
> Communicate asynchronously from a renderer process to the main process.
|
|
|
|
Process: [Renderer](../glossary.md#renderer-process)
|
|
|
|
The `ipcRenderer` module is an [EventEmitter][event-emitter]. It provides a few
|
|
methods so you can send synchronous and asynchronous messages from the render
|
|
process (web page) to the main process. You can also receive replies from the
|
|
main process.
|
|
|
|
See [ipcMain](ipc-main.md) for code examples.
|
|
|
|
## Methods
|
|
|
|
The `ipcRenderer` module has the following method to listen for events and send messages:
|
|
|
|
### `ipcRenderer.on(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
* `event` IpcRendererEvent
|
|
* `...args` any[]
|
|
|
|
Listens to `channel`, when a new message arrives `listener` would be called with
|
|
`listener(event, args...)`.
|
|
|
|
### `ipcRenderer.once(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
* `event` IpcRendererEvent
|
|
* `...args` any[]
|
|
|
|
Adds a one time `listener` function for the event. This `listener` is invoked
|
|
only the next time a message is sent to `channel`, after which it is removed.
|
|
|
|
### `ipcRenderer.removeListener(channel, listener)`
|
|
|
|
* `channel` String
|
|
* `listener` Function
|
|
* `...args` any[]
|
|
|
|
Removes the specified `listener` from the listener array for the specified
|
|
`channel`.
|
|
|
|
### `ipcRenderer.removeAllListeners(channel)`
|
|
|
|
* `channel` String
|
|
|
|
Removes all listeners, or those of the specified `channel`.
|
|
|
|
### `ipcRenderer.send(channel, ...args)`
|
|
|
|
* `channel` String
|
|
* `...args` any[]
|
|
|
|
Send an asynchronous message to the main process via `channel`, along with
|
|
arguments. Arguments will be serialized with the [Structured Clone
|
|
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
|
|
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
|
|
throw an exception.
|
|
|
|
> **NOTE**: Sending non-standard JavaScript types such as DOM objects or
|
|
> special Electron objects is deprecated, and will begin throwing an exception
|
|
> starting with Electron 9.
|
|
|
|
The main process handles it by listening for `channel` with the
|
|
[`ipcMain`](ipc-main.md) module.
|
|
|
|
### `ipcRenderer.invoke(channel, ...args)`
|
|
|
|
* `channel` String
|
|
* `...args` any[]
|
|
|
|
Returns `Promise<any>` - Resolves with the response from the main process.
|
|
|
|
Send a message to the main process via `channel` and expect a result
|
|
asynchronously. Arguments will be serialized with the [Structured Clone
|
|
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
|
|
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
|
|
throw an exception.
|
|
|
|
> **NOTE**: Sending non-standard JavaScript types such as DOM objects or
|
|
> special Electron objects is deprecated, and will begin throwing an exception
|
|
> starting with Electron 9.
|
|
|
|
The main process should listen for `channel` with
|
|
[`ipcMain.handle()`](ipc-main.md#ipcmainhandlechannel-listener).
|
|
|
|
For example:
|
|
```javascript
|
|
// 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
|
|
})
|
|
```
|
|
|
|
### `ipcRenderer.sendSync(channel, ...args)`
|
|
|
|
* `channel` String
|
|
* `...args` any[]
|
|
|
|
Returns `any` - The value sent back by the [`ipcMain`](ipc-main.md) handler.
|
|
|
|
Send a message to the main process via `channel` and expect a result
|
|
synchronously. Arguments will be serialized with the [Structured Clone
|
|
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
|
|
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
|
|
throw an exception.
|
|
|
|
> **NOTE**: Sending non-standard JavaScript types such as DOM objects or
|
|
> special Electron objects is deprecated, and will begin throwing an exception
|
|
> starting with Electron 9.
|
|
|
|
The main process handles it by listening for `channel` with [`ipcMain`](ipc-main.md) module,
|
|
and replies by setting `event.returnValue`.
|
|
|
|
> :warning: **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()`](ipc-renderer.md#ipcrendererinvokechannel-args).
|
|
|
|
### `ipcRenderer.sendTo(webContentsId, channel, ...args)`
|
|
|
|
* `webContentsId` Number
|
|
* `channel` String
|
|
* `...args` any[]
|
|
|
|
Sends a message to a window with `webContentsId` via `channel`.
|
|
|
|
### `ipcRenderer.sendToHost(channel, ...args)`
|
|
|
|
* `channel` String
|
|
* `...args` any[]
|
|
|
|
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
|
|
the host page instead of the main process.
|
|
|
|
## Event object
|
|
|
|
The documentation for the `event` object passed to the `callback` can be found
|
|
in the [`ipc-renderer-event`](structures/ipc-renderer-event.md) structure docs.
|
|
|
|
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
|
|
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
|
|
[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
|