feat: add ipcRenderer.invoke() (#18449)

This commit is contained in:
Jeremy Apthorp 2019-05-31 10:25:19 -07:00 committed by GitHub
parent b180fb376c
commit c436997840
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 389 additions and 20 deletions

View file

@ -88,7 +88,61 @@ Removes the specified `listener` from the listener array for the specified
Removes listeners of the specified `channel`.
## Event object
### `ipcMain.handle(channel, listener)`
* `channel` String
* `listener` Function<Promise> | Function<any>
* `event` IpcMainInvokeEvent
* `...args` any[]
Adds a handler for an `invoke`able IPC. This handler will be called whenever a
renderer calls `ipcRenderer.invoke(channel, ...args)`.
If `listener` returns a Promise, the eventual result of the promise will be
returned as a reply to the remote caller. Otherwise, the return value of the
listener will be used as the value of the reply.
```js
// Main process
ipcMain.handle('my-invokable-ipc', async (event, ...args) => {
const result = await somePromise(...args)
return result
})
// Renderer process
async () => {
const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)
// ...
}
```
The `event` that is passed as the first argument to the handler is the same as
that passed to a regular event listener. It includes information about which
WebContents is the source of the invoke request.
### `ipcMain.handleOnce(channel, listener)`
* `channel` String
* `listener` Function<Promise> | Function<any>
* `event` IpcMainInvokeEvent
* `...args` any[]
Handles a single `invoke`able IPC message, then removes the listener. See
`ipcMain.handle(channel, listener)`.
### `ipcMain.removeHandler(channel)`
* `channel` String
Removes any handler for `channel`, if present.
## IpcMainEvent object
The documentation for the `event` object passed to the `callback` can be found
in the [`ipc-main-event`](structures/ipc-main-event.md) structure docs.
## IpcMainInvokeEvent object
The documentation for the `event` object passed to `handle` callbacks can be
found in the [`ipc-main-invoke-event`](structures/ipc-main-invoke-event.md)
structure docs.

View file

@ -57,10 +57,39 @@ Removes all listeners, or those of the specified `channel`.
* `...args` any[]
Send a message to the main process asynchronously via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and
send arbitrary arguments. Arguments will be serialized as JSON internally and
hence no functions or prototype chain will be included.
The main process handles it by listening for `channel` with [`ipcMain`](ipc-main.md) module.
The main process handles it by listening for `channel` with the
[`ipcMain`](ipc-main.md) module.
### `ipcRenderer.invoke(channel[, arg1][, arg2][, ...])`
* `channel` String
* `...args` any[]
Returns `Promise<any>` - Resolves with the response from the main process.
Send a message to the main process asynchronously via `channel` and expect an
asynchronous result. Arguments will be serialized as JSON internally and
hence no functions or prototype chain will be included.
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[, arg1][, arg2][, ...])`

View file

@ -5,4 +5,3 @@
* `sender` WebContents - Returns the `webContents` that sent the message
* `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guaruntee the reply will go to the correct process and frame.
* `...args` any[]
IpcRenderer

View file

@ -0,0 +1,4 @@
# IpcMainInvokeEvent Object extends `Event`
* `frameId` Integer - The ID of the renderer frame that sent this message
* `sender` WebContents - Returns the `webContents` that sent the message