ipcRenderer

History

Version(s)	Changes
None	ipcRenderer는 더 이상 contextBridge를 통해 전송할 수 없음

렌더러 프로세스에서 메인 프로세스로 비동기 통신을 수행한다.

프로세스: 렌더러

ipcRenderer 모듈은 EventEmitter다. 이 모듈은 렌더러 프로세스(웹 페이지)에서 메인 프로세스로 동기 및 비동기 메시지를 보낼 수 있는 몇 가지 메서드를 제공한다. 또한 메인 프로세스로부터 응답을 받을 수도 있다.

코드 예제는 IPC 튜토리얼을 참고한다.

메서드

ipcRenderer 모듈은 이벤트를 수신하고 메시지를 보내기 위해 다음과 같은 메서드를 제공한다:

ipcRenderer.on(channel, listener)

• channel string
• listener Function
  • event IpcRendererEvent
  • ...args any[]

channel을 구독하며, 새로운 메시지가 도착하면 listener(event, args...) 형태로 리스너가 호출된다.

warning

보안상의 이유로 event 인자를 렌더러에 노출하지 말아야 한다! 렌더러에서 받은 콜백을 다음과 같은 방식으로 다른 함수로 감싸야 한다:
ipcRenderer.on('my-channel', (event, ...args) => callback(...args)).
이렇게 콜백을 감싸지 않으면 위험한 Electron API가 렌더러 프로세스에 노출될 수 있다.
자세한 내용은 보안 가이드를 참고한다.

ipcRenderer.off(channel, listener)

• channel string
• listener Function
  • event IpcRendererEvent
  • ...args any[]

지정된 channel에 등록된 리스너 배열에서 특정 listener를 제거한다.

ipcRenderer.once(channel, listener)

• channel string
• listener Function
  • event IpcRendererEvent
  • ...args any[]

이벤트에 대해 한 번만 실행되는 listener 함수를 추가한다. 이 listener는 channel로 메시지가 전송될 때 단 한 번만 호출되며, 이후에는 제거된다.

ipcRenderer.addListener(channel, listener)

• channel string
• listener Function
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.on의 별칭이다.

ipcRenderer.removeListener(channel, listener)

• channel string
• listener Function
  • event IpcRendererEvent
  • ...args any[]

ipcRenderer.off의 별칭이다.

ipcRenderer.removeAllListeners([channel])

• channel string (옵션)

지정된 channel에서 모든 리스너를 제거한다. channel이 지정되지 않으면 모든 채널의 리스너를 제거한다.

ipcRenderer.send(channel, ...args)

• channel string
• ...args any[]

channel을 통해 메인 프로세스로 비동기 메시지를 보낸다. 이때 추가 인자를 함께 전달할 수 있다. 인자는 Structured Clone Algorithm을 사용해 직렬화되며, window.postMessage와 마찬가지로 프로토타입 체인은 포함되지 않는다. 함수, Promise, Symbol, WeakMap, WeakSet을 전송하려고 하면 예외가 발생한다.

참고: DOM 객체나 특수한 Electron 객체와 같은 비표준 자바스크립트 타입을 전송하려고 하면 예외가 발생한다.

메인 프로세스는 ImageBitmap, File, DOMMatrix와 같은 DOM 객체를 지원하지 않기 때문에, 이러한 객체는 Electron IPC를 통해 메인 프로세스로 전송할 수 없다. 메인 프로세스가 이를 디코딩할 방법이 없기 때문이다. 이러한 객체를 IPC로 전송하려고 하면 오류가 발생한다.

메인 프로세스는 ipcMain 모듈을 사용해 channel을 수신하며, 이를 처리한다.

MessagePort를 메인 프로세스로 전송해야 한다면, ipcRenderer.postMessage를 사용한다.

메소드 호출 결과와 같이 메인 프로세스로부터 단일 응답을 받아야 하는 경우, ipcRenderer.invoke를 고려한다.

ipcRenderer.invoke(channel, ...args)

• channel string
• ...args any[]

반환값: Promise<any> - 메인 프로세스로부터의 응답을 반환한다.

channel을 통해 메인 프로세스로 메시지를 보내고 비동기적으로 결과를 기대한다. 인자는 window.postMessage와 마찬가지로 Structured Clone Algorithm로 직렬화된다. 따라서 프로토타입 체인은 포함되지 않는다. 함수, Promise, Symbol, WeakMap, WeakSet을 보내려고 하면 예외가 발생한다.

메인 프로세스는 ipcMain.handle()를 사용해 channel을 수신해야 한다.

예제:

// 렌더러 프로세스
ipcRenderer.invoke('some-name', someArgument).then((result) => {
  // ...
})

// 메인 프로세스
ipcMain.handle('some-name', async (event, someArgument) => {
  const result = await doSomeWork(someArgument)
  return result
})

MessagePort를 메인 프로세스로 전송해야 한다면 ipcRenderer.postMessage를 사용한다.

메시지에 대한 응답이 필요하지 않다면 ipcRenderer.send를 고려한다.

참고 DOM 객체나 특수한 Electron 객체와 같은 비표준 JavaScript 타입을 보내려고 하면 예외가 발생한다.

메인 프로세스는 ImageBitmap, File, DOMMatrix와 같은 DOM 객체를 지원하지 않으므로, 이러한 객체는 Electron의 IPC를 통해 메인 프로세스로 전송할 수 없다. 메인 프로세스가 이를 디코딩할 방법이 없기 때문이다. IPC를 통해 이러한 객체를 전송하려고 하면 오류가 발생한다.

참고 메인 프로세스의 핸들러가 오류를 던지면, invoke가 반환한 Promise는 거부된다. 그러나 렌더러 프로세스의 Error 객체는 메인 프로세스에서 던진 것과 동일하지 않다.

ipcRenderer.sendSync(channel, ...args)

• channel string
• ...args any[]

반환값 any - ipcMain 핸들러가 보낸 값

channel을 통해 메인 프로세스로 메시지를 보내고 동기적으로 결과를 기다린다. 인자는 window.postMessage와 같이 Structured Clone Algorithm로 직렬화되므로 프로토타입 체인은 포함되지 않는다. 함수, Promise, Symbol, WeakMap, WeakSet을 보내면 예외가 발생한다.

참고: DOM 객체나 특수한 Electron 객체와 같은 비표준 자바스크립트 타입을 보내면 예외가 발생한다.

메인 프로세스는 ImageBitmap, File, DOMMatrix와 같은 DOM 객체를 지원하지 않으므로, 이러한 객체는 Electron의 IPC를 통해 메인 프로세스로 보낼 수 없다. 메인 프로세스가 이를 디코딩할 방법이 없기 때문이다. IPC를 통해 이러한 객체를 보내려고 시도하면 오류가 발생한다.

메인 프로세스는 ipcMain 모듈로 channel을 수신하고, event.returnValue를 설정하여 응답한다.

⚠️ 경고: 동기 메시지를 보내면 응답을 받을 때까지 렌더러 프로세스 전체가 블로킹된다. 따라서 이 메서드는 최후의 수단으로만 사용해야 한다. 비동기 버전인 invoke()를 사용하는 것이 훨씬 더 좋다.

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

• channel string
• message any
• transfer MessagePort[] (선택 사항)

메인 프로세스로 메시지를 보내며, 선택적으로 하나 이상의 MessagePort 객체의 소유권을 전달한다.

전달된 MessagePort 객체는 메인 프로세스에서 MessagePortMain 객체로 사용할 수 있다. 이벤트가 발생할 때 ports 속성에 접근하면 된다.

예를 들면 다음과 같다:

// 렌더러 프로세스
const { port1, port2 } = new MessageChannel()
ipcRenderer.postMessage('port', { message: 'hello' }, [port1])

// 메인 프로세스
ipcMain.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

MessagePort와 MessageChannel 사용에 대한 더 자세한 정보는 MDN 문서를 참고한다.

ipcRenderer.sendToHost(channel, ...args)

• channel string
• ...args any[]

ipcRenderer.send와 유사하지만, 이벤트가 메인 프로세스 대신 호스트 페이지의 <webview> 엘리먼트로 전송된다.