docs: Make ipcRenderer and ipcMain listener API docs consistent (#44651)
* docs: Make ipcRenderer and ipcMain listener API docs consistent * test: add some unit tests for ipcRenderer/ipcMain listener behavior * fix: Mark on/off methods as primary and addListener/removeListener as aliases * fix: clear all listeners before running ipcMain removeAllListeners tests
This commit is contained in:
parent
aa7a5e6ca9
commit
10d967028a
4 changed files with 86 additions and 10 deletions
|
@ -32,7 +32,7 @@ process, see [webContents.send][web-contents-send] for more information.
|
||||||
|
|
||||||
## Methods
|
## Methods
|
||||||
|
|
||||||
The `ipcMain` module has the following method to listen for events:
|
The `ipcMain` module has the following methods to listen for events:
|
||||||
|
|
||||||
### `ipcMain.on(channel, listener)`
|
### `ipcMain.on(channel, listener)`
|
||||||
|
|
||||||
|
@ -44,6 +44,16 @@ The `ipcMain` module has the following method to listen for events:
|
||||||
Listens to `channel`, when a new message arrives `listener` would be called with
|
Listens to `channel`, when a new message arrives `listener` would be called with
|
||||||
`listener(event, args...)`.
|
`listener(event, args...)`.
|
||||||
|
|
||||||
|
### `ipcMain.off(channel, listener)`
|
||||||
|
|
||||||
|
* `channel` string
|
||||||
|
* `listener` Function
|
||||||
|
* `event` [IpcMainEvent][ipc-main-event]
|
||||||
|
* `...args` any[]
|
||||||
|
|
||||||
|
Removes the specified `listener` from the listener array for the specified
|
||||||
|
`channel`.
|
||||||
|
|
||||||
### `ipcMain.once(channel, listener)`
|
### `ipcMain.once(channel, listener)`
|
||||||
|
|
||||||
* `channel` string
|
* `channel` string
|
||||||
|
@ -54,20 +64,28 @@ Listens to `channel`, when a new message arrives `listener` would be called with
|
||||||
Adds a one time `listener` function for the event. This `listener` is invoked
|
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.
|
only the next time a message is sent to `channel`, after which it is removed.
|
||||||
|
|
||||||
|
### `ipcMain.addListener(channel, listener)`
|
||||||
|
|
||||||
|
* `channel` string
|
||||||
|
* `listener` Function
|
||||||
|
* `event` [IpcMainEvent][ipc-main-event]
|
||||||
|
* `...args` any[]
|
||||||
|
|
||||||
|
Alias for [`ipcMain.on`](#ipcmainonchannel-listener).
|
||||||
|
|
||||||
### `ipcMain.removeListener(channel, listener)`
|
### `ipcMain.removeListener(channel, listener)`
|
||||||
|
|
||||||
* `channel` string
|
* `channel` string
|
||||||
* `listener` Function
|
* `listener` Function
|
||||||
* `...args` any[]
|
* `...args` any[]
|
||||||
|
|
||||||
Removes the specified `listener` from the listener array for the specified
|
Alias for [`ipcMain.off`](#ipcmainoffchannel-listener).
|
||||||
`channel`.
|
|
||||||
|
|
||||||
### `ipcMain.removeAllListeners([channel])`
|
### `ipcMain.removeAllListeners([channel])`
|
||||||
|
|
||||||
* `channel` string (optional)
|
* `channel` string (optional)
|
||||||
|
|
||||||
Removes listeners of the specified `channel`.
|
Removes all listeners from the specified `channel`. Removes all listeners from all channels if no channel is specified.
|
||||||
|
|
||||||
### `ipcMain.handle(channel, listener)`
|
### `ipcMain.handle(channel, listener)`
|
||||||
|
|
||||||
|
|
|
@ -48,7 +48,8 @@ Listens to `channel`, when a new message arrives `listener` would be called with
|
||||||
* `event` [IpcRendererEvent][ipc-renderer-event]
|
* `event` [IpcRendererEvent][ipc-renderer-event]
|
||||||
* `...args` any[]
|
* `...args` any[]
|
||||||
|
|
||||||
Alias for [`ipcRenderer.removeListener`](#ipcrendererremovelistenerchannel-listener).
|
Removes the specified `listener` from the listener array for the specified
|
||||||
|
`channel`.
|
||||||
|
|
||||||
### `ipcRenderer.once(channel, listener)`
|
### `ipcRenderer.once(channel, listener)`
|
||||||
|
|
||||||
|
@ -76,14 +77,13 @@ Alias for [`ipcRenderer.on`](#ipcrendereronchannel-listener).
|
||||||
* `event` [IpcRendererEvent][ipc-renderer-event]
|
* `event` [IpcRendererEvent][ipc-renderer-event]
|
||||||
* `...args` any[]
|
* `...args` any[]
|
||||||
|
|
||||||
Removes the specified `listener` from the listener array for the specified
|
Alias for [`ipcRenderer.off`](#ipcrendereroffchannel-listener).
|
||||||
`channel`.
|
|
||||||
|
|
||||||
### `ipcRenderer.removeAllListeners(channel)`
|
### `ipcRenderer.removeAllListeners([channel])`
|
||||||
|
|
||||||
* `channel` string
|
* `channel` string (optional)
|
||||||
|
|
||||||
Removes all listeners, or those of the specified `channel`.
|
Removes all listeners from the specified `channel`. Removes all listeners from all channels if no channel is specified.
|
||||||
|
|
||||||
### `ipcRenderer.send(channel, ...args)`
|
### `ipcRenderer.send(channel, ...args)`
|
||||||
|
|
||||||
|
|
|
@ -92,4 +92,27 @@ describe('ipc main module', () => {
|
||||||
expect(v).to.equal('hello');
|
expect(v).to.equal('hello');
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
|
describe('ipcMain.removeAllListeners', () => {
|
||||||
|
beforeEach(() => { ipcMain.removeAllListeners(); });
|
||||||
|
beforeEach(() => { ipcMain.removeAllListeners(); });
|
||||||
|
|
||||||
|
it('removes only the given channel', () => {
|
||||||
|
ipcMain.on('channel1', () => {});
|
||||||
|
ipcMain.on('channel2', () => {});
|
||||||
|
|
||||||
|
ipcMain.removeAllListeners('channel1');
|
||||||
|
|
||||||
|
expect(ipcMain.eventNames()).to.deep.equal(['channel2']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('removes all channels if no channel is specified', () => {
|
||||||
|
ipcMain.on('channel1', () => {});
|
||||||
|
ipcMain.on('channel2', () => {});
|
||||||
|
|
||||||
|
ipcMain.removeAllListeners();
|
||||||
|
|
||||||
|
expect(ipcMain.eventNames()).to.deep.equal([]);
|
||||||
|
});
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|
|
@ -18,6 +18,7 @@ describe('ipcRenderer module', () => {
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
await w.loadURL('about:blank');
|
await w.loadURL('about:blank');
|
||||||
|
w.webContents.on('console-message', (event, ...args) => console.error(...args));
|
||||||
});
|
});
|
||||||
after(async () => {
|
after(async () => {
|
||||||
await closeWindow(w);
|
await closeWindow(w);
|
||||||
|
@ -144,6 +145,40 @@ describe('ipcRenderer module', () => {
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
|
describe('ipcRenderer.removeAllListeners', () => {
|
||||||
|
it('removes only the given channel', async () => {
|
||||||
|
const result = await w.webContents.executeJavaScript(`
|
||||||
|
(() => {
|
||||||
|
const { ipcRenderer } = require('electron');
|
||||||
|
|
||||||
|
ipcRenderer.on('channel1', () => {});
|
||||||
|
ipcRenderer.on('channel2', () => {});
|
||||||
|
|
||||||
|
ipcRenderer.removeAllListeners('channel1');
|
||||||
|
|
||||||
|
return ipcRenderer.eventNames();
|
||||||
|
})()
|
||||||
|
`);
|
||||||
|
expect(result).to.deep.equal(['channel2']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('removes all channels if no channel is specified', async () => {
|
||||||
|
const result = await w.webContents.executeJavaScript(`
|
||||||
|
(() => {
|
||||||
|
const { ipcRenderer } = require('electron');
|
||||||
|
|
||||||
|
ipcRenderer.on('channel1', () => {});
|
||||||
|
ipcRenderer.on('channel2', () => {});
|
||||||
|
|
||||||
|
ipcRenderer.removeAllListeners();
|
||||||
|
|
||||||
|
return ipcRenderer.eventNames();
|
||||||
|
})()
|
||||||
|
`);
|
||||||
|
expect(result).to.deep.equal([]);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
describe('after context is released', () => {
|
describe('after context is released', () => {
|
||||||
it('throws an exception', async () => {
|
it('throws an exception', async () => {
|
||||||
const error = await w.webContents.executeJavaScript(`(${() => {
|
const error = await w.webContents.executeJavaScript(`(${() => {
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue