ipcRenderer

Асинхронное взаимодействие между процессом рендеринга и основным процессом.

Процесс: Рендеринг

Модуль ipcRenderer является EventEmitter. Он предоставляет несколько методов для отправки синхронных и асинхронных сообщений из процесса рендеринга (веб-страницы) в основной процесс. Вы также можете получать ответы от основного процесса.

Примеры кода см. в учебнике по IPC.

Методы​

В модуле ipcRenderer есть следующие методы для прослушивания событий и отправки сообщений:

ipcRenderer.on(channel, listener)​

• channel строка
• listener Функция
  • event IpcRendererEvent
  • ...args любой[]

Прослушивает channel, при поступлении нового сообщения вызывается listener с listener(event, args...).

ipcRenderer.once(channel, listener)​

• channel строка
• listener Функция
  • event IpcRendererEvent
  • ...args любой[]

Добавляет одноразовую функцию listener для события. Эта функция listener вызывается только в следующий раз, когда сообщение отправляется в channel, после чего удаляется.

ipcRenderer.removeListener(channel, listener)​

• channel строка
• listener Функция
  • ...args любой[]

Удаляет указанную listener из массива обработчиков для указанного channel.

ipcRenderer.removeAllListeners(channel)​

• channel строка

Удаляет все обработчики или только указанные обработчики channel.

ipcRenderer.send(channel, ...args)​

• channel строка
• ...args любой[]

Отправляет асинхронное сообщение в основной процесс через channel, вместе с аргументами. Аргументы сериализуются с помощью алгоритма Структурированного клонирования, аналогично window.postMessage, поэтому цепочки прототипов не будут включены. Отправка функций, обещаний, символов, WeakMap или WeakSet приведет к ошибке.

ПРИМЕЧАНИЕ: Отправка нестандартных типов JavaScript, таких как объекты DOM или специальные объекты Electron, приведет к ошибке.

Поскольку основной процесс не поддерживает объекты DOM, такие как ImageBitmap, File, DOMMatrix и т. д., такие объекты не могут быть отправлены через IPC Electron в основной процесс, так как основной процесс не сможет их декодировать. Попытка отправки таких объектов через IPC приведет к ошибке.

Основной процесс обрабатывает это, прослушивая channel с помощью модуля ipcMain.

Если вам нужно передать MessagePort в основной процесс, используйте ipcRenderer.postMessage.

Если вам нужно получить единственный ответ от основного процесса, например, результат вызова метода, рассмотрите использование ipcRenderer.invoke.

ipcRenderer.invoke(channel, ...args)​

• channel строка
• ...args любой[]

Возвращает Promise<any> - выполняется с ответом от основного процесса.

Отправляет сообщение в основной процесс через channel и асинхронно ожидает результат. Аргументы сериализуются с помощью алгоритма Структурированного клонирования, аналогично window.postMessage, поэтому цепочки прототипов не будут включены. Отправка функций, обещаний, символов, WeakMap или WeakSet приведет к ошибке.

ПРИМЕЧАНИЕ: Отправка нестандартных типов JavaScript, таких как объекты DOM или специальные объекты Electron, приведет к ошибке.

Поскольку основной процесс не поддерживает объекты DOM, такие как ImageBitmap, File, DOMMatrix и т. д., такие объекты не могут быть отправлены через IPC Electron в основной процесс, так как основной процесс не сможет их декодировать. Попытка отправки таких объектов через IPC приведет к ошибке.

Основной процесс должен прослушивать channel с помощью ipcMain.handle().

Например:

// 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.

ipcRenderer.sendSync(channel, ...args)​

• channel строка
• ...args любой[]

Возвращает any - значение, отправленное обратно обработчиком ipcMain.

Отправляет сообщение в основной процесс через channel и синхронно ожидает результат. Аргументы сериализуются с помощью алгоритма Структурированного клонирования, аналогично window.postMessage, поэтому цепочки прототипов не будут включены. Отправка функций, обещаний, символов, WeakMap или WeakSet приведет к ошибке.

ПРИМЕЧАНИЕ: Отправка нестандартных типов JavaScript, таких как объекты DOM или специальные объекты Electron, приведет к ошибке.

Поскольку основной процесс не поддерживает объекты DOM, такие как ImageBitmap, File, DOMMatrix и т. д., такие объекты не могут быть отправлены через IPC Electron в основной процесс, так как основной процесс не сможет их декодировать. Попытка отправки таких объектов через IPC приведет к ошибке.

Основной процесс обрабатывает это, прослушивая channel с помощью модуля ipcMain, и отвечает, установив event.returnValue.

⚠️ ПРЕДУПРЕЖДЕНИЕ: Отправка синхронного сообщения заблокирует весь процесс рендеринга до получения ответа, поэтому используйте этот метод только в крайнем случае. Гораздо лучше использовать асинхронную версию invoke().

ipcRenderer.postMessage(channel, message, [transfer])​

• channel строка
• message любой
• 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.sendTo(webContentsId, channel, ...args)​

• webContentsId число
• channel строка
• ...args любой[]

Отправляет сообщение в окно с webContentsId через channel.

ipcRenderer.sendToHost(channel, ...args)​

• channel строка
• ...args любой[]

Аналогично ipcRenderer.send, но событие будет отправлено в элемент <webview> на странице хоста, а не в основной процесс.

Объект события​

Документация для объекта event, переданного в callback, находится в документации структуры ipc-renderer-event.