webContents

웹 페이지를 렌더링하고 제어한다.

프로세스: Main

webContents는 EventEmitter이다. 웹 페이지를 렌더링하고 제어하는 역할을 하며, BrowserWindow 객체의 속성이다. webContents 객체에 접근하는 예제는 다음과 같다:

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://github.com')

const contents = win.webContents
console.log(contents)

네비게이션 이벤트

webContents 내에서 발생하는 네비게이션을 실시간으로 모니터링할 수 있는 여러 이벤트가 있다.

문서 네비게이션

webContents가 다른 페이지로 이동할 때(페이지 내 네비게이션과 달리), 다음과 같은 이벤트가 발생한다.

did-start-navigation
will-frame-navigate
will-navigate (메인 프레임이 이동할 때만 발생)
will-redirect (네비게이션 중 리다이렉트가 발생할 때만 발생)
did-redirect-navigation (네비게이션 중 리다이렉트가 발생할 때만 발생)
did-frame-navigate
did-navigate (메인 프레임이 이동할 때만 발생)

취소 가능한 이벤트 중 하나에서 event.preventDefault()를 호출하면 이후 이벤트는 발생하지 않는다.

페이지 내 네비게이션

페이지 내 네비게이션은 페이지를 새로 고침하지 않고 현재 페이지 내의 특정 위치로 이동한다. 이러한 이벤트는 취소할 수 없다. 페이지 내 네비게이션이 발생할 때, 다음과 같은 순서로 이벤트가 실행된다:

프레임 네비게이션

will-navigate와 did-navigate 이벤트는 mainFrame이 네비게이션할 때만 발생한다. <iframe> 내부의 네비게이션도 관찰하려면 will-frame-navigate와 did-frame-navigate 이벤트를 사용해야 한다.

메서드

이 메서드들은 webContents 모듈에서 접근할 수 있다:

const { webContents } = require('electron')
console.log(webContents)

`webContents.getAllWebContents()`

WebContents[] 타입을 반환한다. 이 배열은 모든 WebContents 인스턴스를 포함한다. 여기에는 모든 윈도우, 웹뷰, 열린 개발자 도구, 그리고 개발자 도구 확장 프로그램의 백그라운드 페이지에 대한 웹 콘텐츠가 포함된다.

`webContents.getFocusedWebContents()`

WebContents | null 타입의 값을 반환한다. 현재 애플리케이션에서 포커스된 웹 콘텐츠를 반환하며, 포커스된 콘텐츠가 없으면 null을 반환한다.

`webContents.fromId(id)`

id Integer

주어진 ID에 해당하는 WebContents 인스턴스를 반환한다. 만약 해당 ID와 연결된 WebContents가 없다면 undefined를 반환한다.

`webContents.fromFrame(frame)`

frame WebFrameMain

WebContents | undefined를 반환한다. 주어진 WebFrameMain에 연결된 WebContents 인스턴스를 반환하며, 해당 WebFrameMain과 연결된 WebContents가 없을 경우 undefined를 반환한다.

`webContents.fromDevToolsTargetId(targetId)`

targetId string - WebContents 인스턴스와 연결된 Chrome DevTools 프로토콜의 TargetID.

WebContents | undefined를 반환한다. 주어진 TargetID에 해당하는 WebContents 인스턴스를 반환하거나, 해당 TargetID와 연결된 WebContents가 없으면 undefined를 반환한다.

Chrome DevTools 프로토콜과 통신할 때, 할당된 TargetID를 기반으로 WebContents 인스턴스를 조회하는 것이 유용할 수 있다.

async function lookupTargetId (browserWindow) {
  const wc = browserWindow.webContents
  await wc.debugger.attach('1.3')
  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
  const { targetId } = targetInfo
  const targetWebContents = await wc.fromDevToolsTargetId(targetId)
}

WebContents 클래스

BrowserWindow 인스턴스의 내용을 렌더링하고 제어한다.

프로세스: 메인
이 클래스는 'electron' 모듈에서 직접 내보내지 않는다. Electron API의 다른 메서드 반환값으로만 사용할 수 있다.

인스턴스 이벤트

이벤트: 'did-finish-load'

네비게이션이 완료되었을 때 발생한다. 즉, 탭의 스피너가 멈추고 onload 이벤트가 전달된 시점에 이 이벤트가 발생한다.

이벤트: 'did-fail-load'

반환 값:

event Event
errorCode Integer
errorDescription string
validatedURL string
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

이 이벤트는 did-finish-load와 유사하지만, 로드가 실패했을 때 발생한다.
에러 코드의 전체 목록과 그 의미는 여기에서 확인할 수 있다.

이벤트: 'did-fail-provisional-load'

반환값:

event Event
errorCode Integer
errorDescription string
validatedURL string
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

이 이벤트는 did-fail-load와 유사하지만, 로드가 취소된 경우(예: window.stop()이 호출된 경우)에 발생한다.

이벤트: 'did-frame-finish-load'

반환 값:

event Event
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

이 이벤트는 프레임의 네비게이션이 완료되었을 때 발생한다.

이벤트: 'did-start-loading'

이 이벤트는 탭의 스피너가 회전하기 시작하는 시점에 해당한다.

이벤트: 'did-stop-loading'

이 이벤트는 탭의 스피너가 회전을 멈춘 시점에 발생한다.

이벤트: 'dom-ready'

최상위 프레임의 문서가 로드되면 발생한다.

이벤트: 'page-title-updated'

반환값:

event Event
title string
explicitSet boolean

이 이벤트는 네비게이션 중 페이지 제목이 설정될 때 발생한다. explicitSet은 파일 URL에서 제목이 자동으로 생성된 경우 false가 된다.

이벤트: 'page-favicon-updated'

반환값:

event Event
favicons string[] - URL 배열

페이지가 파비콘 URL을 수신할 때 발생한다.

이벤트: 'content-bounds-updated'

반환값:

event Event
bounds Rectangle - 요청된 새로운 콘텐츠 경계

이 이벤트는 페이지가 window.moveTo, window.resizeTo 또는 관련 API를 호출할 때 발생한다.

기본적으로 이 이벤트는 윈도우를 이동시킨다. 이 동작을 방지하려면 event.preventDefault()를 호출하면 된다.

이벤트: 'did-create-window'

반환 값:

window BrowserWindow
details Object
- url string - 생성된 윈도우의 URL.
- frameName string - window.open() 호출에서 생성된 윈도우에 부여된 이름.
- options BrowserWindowConstructorOptions - BrowserWindow를 생성할 때 사용된 옵션. 이 옵션은 우선순위에 따라 병합된다: window.open()의 features 문자열에서 파싱된 옵션, 부모로부터 상속된 보안 관련 webPreferences, 그리고 webContents.setWindowOpenHandler에서 제공된 옵션. 인식되지 않는 옵션은 필터링되지 않는다.
- referrer Referrer - 새 윈도우에 전달될 리퍼러. 리퍼러 정책에 따라 Referer 헤더가 전송될 수도 있고, 그렇지 않을 수도 있다.
- postBody PostBody (선택 사항) - 새 윈도우로 전송될 POST 데이터와 함께 설정될 적절한 헤더. 전송될 POST 데이터가 없으면 값은 null이 된다. 이 값은 target=_blank로 설정된 폼에 의해 윈도우가 생성될 때만 정의된다.
- disposition string - default, foreground-tab, background-tab, new-window 또는 other 중 하나의 값을 가질 수 있다.

렌더러에서 window.open을 통해 윈도우가 성공적으로 생성된 후에 발생한다. 만약 윈도우 생성이 webContents.setWindowOpenHandler에서 취소되면 이 이벤트는 발생하지 않는다.

자세한 내용과 webContents.setWindowOpenHandler와 함께 사용하는 방법은 window.open()을 참고한다.

이벤트: 'will-navigate'

반환값:

details Event<>
- url string - 프레임이 이동하려는 URL
- isSameDocument boolean - 이 이벤트는 window.history API를 사용한 동일 문서 내 네비게이션과 참조 프래그먼트 네비게이션에 대해 발생하지 않는다. 이 이벤트에서는 항상 false로 설정된다.
- isMainFrame boolean - 네비게이션이 메인 프레임에서 일어나는 경우 true
- frame WebFrameMain | null - 이동할 프레임. 프레임이 이미 이동했거나 삭제된 후에 접근하면 null이 될 수 있다.
- initiator WebFrameMain | null (선택사항) - 네비게이션을 시작한 프레임. 부모 프레임(예: window.open을 통해 프레임 이름으로 열린 경우)일 수 있으며, 프레임이 아닌 다른 방식으로 네비게이션이 시작된 경우 null이 된다. 이벤트가 발생하기 전에 시작 프레임이 삭제된 경우에도 null이 될 수 있다.
url string Deprecated
isInPlace boolean Deprecated
isMainFrame boolean Deprecated
frameProcessId Integer Deprecated
frameRoutingId Integer Deprecated

사용자 또는 페이지가 메인 프레임에서 네비게이션을 시작하려고 할 때 발생한다. window.location 객체가 변경되거나 사용자가 페이지 내 링크를 클릭할 때 일어날 수 있다.

이 이벤트는 webContents.loadURL이나 webContents.back과 같은 API를 통해 프로그래밍적으로 네비게이션이 시작된 경우에는 발생하지 않는다.

또한 앵커 링크를 클릭하거나 window.location.hash를 업데이트하는 등의 페이지 내 네비게이션에도 발생하지 않는다. 이러한 경우에는 did-navigate-in-page 이벤트를 사용해야 한다.

event.preventDefault()를 호출하면 네비게이션을 방지할 수 있다.

이벤트: 'will-frame-navigate'

반환값:

details Event<>
- url string - 프레임이 이동하려는 URL
- isSameDocument boolean - 이 이벤트는 window.history API를 사용한 동일 문서 내 네비게이션이나 참조 프래그먼트 네비게이션에서는 발생하지 않는다. 이 이벤트에서는 항상 false로 설정된다.
- isMainFrame boolean - 네비게이션이 메인 프레임에서 발생하면 true
- frame WebFrameMain | null - 네비게이션 대상 프레임. 프레임이 이미 이동했거나 삭제된 후에 접근하면 null이 될 수 있다.
- initiator WebFrameMain | null (optional) - 네비게이션을 시작한 프레임. 이는 부모 프레임일 수 있으며(예: window.open을 사용한 경우), 프레임이 아닌 다른 방식으로 네비게이션이 시작된 경우 null이 된다. 또한 이벤트가 발생하기 전에 시작 프레임이 삭제된 경우에도 null이 될 수 있다.

이 이벤트는 사용자나 페이지가 어떤 프레임에서 네비게이션을 시작하려고 할 때 발생한다. window.location 객체가 변경되거나 사용자가 페이지 내 링크를 클릭할 때 트리거될 수 있다.

will-navigate와 달리, will-frame-navigate는 메인 프레임이나 그 하위 프레임이 네비게이션을 시도할 때 발생한다. 네비게이션이 메인 프레임에서 시작된 경우, isMainFrame은 true가 된다.

이 이벤트는 webContents.loadURL이나 webContents.back과 같은 API를 사용해 프로그래밍 방식으로 네비게이션이 시작될 때는 발생하지 않는다.

또한 앵커 링크를 클릭하거나 window.location.hash를 업데이트하는 등 페이지 내 네비게이션에서도 이 이벤트는 발생하지 않는다. 이러한 경우에는 did-navigate-in-page 이벤트를 사용한다.

event.preventDefault()를 호출하면 네비게이션을 방지할 수 있다.

반환값:

details Event<>
- url string - 프레임이 이동하려는 URL
- isSameDocument boolean - 문서 변경 없이 네비게이션이 발생했는지 여부. 같은 문서 내 네비게이션의 예로는 참조 조각(fragment) 네비게이션, pushState/replaceState, 그리고 동일 페이지 내 히스토리 네비게이션이 있다.
- isMainFrame boolean - 네비게이션이 메인 프레임에서 발생하는지 여부
- frame WebFrameMain | null - 이동할 프레임. 프레임이 이미 이동했거나 삭제된 경우 null일 수 있다.
- initiator WebFrameMain | null (optional) - 네비게이션을 시작한 프레임. 부모 프레임일 수 있으며(예: window.open을 사용해 프레임 이름으로 열기), 프레임이 아닌 경우에는 null이 된다. 이벤트가 발생하기 전에 시작 프레임이 삭제된 경우에도 null이 될 수 있다.
url string Deprecated
isInPlace boolean Deprecated
isMainFrame boolean Deprecated
frameProcessId Integer Deprecated
frameRoutingId Integer Deprecated

이 이벤트는 메인 프레임을 포함한 어떤 프레임이 네비게이션을 시작할 때 발생한다.

이벤트: 'will-redirect'

반환값:

details Event<>
- url string - 프레임이 이동하려는 URL.
- isSameDocument boolean - 문서가 변경되지 않고 네비게이션이 발생했는지 여부. 같은 문서 내 네비게이션의 예로는 참조 프래그먼트 네비게이션, pushState/replaceState, 그리고 동일 페이지 내 히스토리 네비게이션이 있다.
- isMainFrame boolean - 네비게이션이 메인 프레임에서 발생하는지 여부.
- frame WebFrameMain | null - 이동할 프레임. 프레임이 이미 이동했거나 삭제된 경우 null이 될 수 있다.
- initiator WebFrameMain | null (선택 사항) - 네비게이션을 시작한 프레임. 이는 부모 프레임일 수 있으며 (예: window.open을 통해 프레임 이름을 사용한 경우), 또는 프레임이 아닌 다른 요소에 의해 시작된 경우 null이 될 수 있다. 또한 이벤트가 발생하기 전에 시작 프레임이 삭제된 경우에도 null이 될 수 있다.
url string Deprecated
isInPlace boolean Deprecated
isMainFrame boolean Deprecated
frameProcessId Integer Deprecated
frameRoutingId Integer Deprecated

서버 측 리다이렉트가 네비게이션 중에 발생할 때 이 이벤트가 발생한다. 예를 들어 302 리다이렉트가 있을 때다.

이 이벤트는 did-start-navigation 이후에 발생하며, 동일한 네비게이션에 대한 did-redirect-navigation 이벤트보다 항상 먼저 발생한다.

event.preventDefault()를 호출하면 네비게이션 (리다이렉트뿐만 아니라)을 막을 수 있다.

반환값:

details Event<>
- url string - 프레임이 이동 중인 URL
- isSameDocument boolean - 문서 변경 없이 네비게이션이 발생했는지 여부. 같은 문서 내 네비게이션의 예로는 참조 프래그먼트 네비게이션, pushState/replaceState, 그리고 동일 페이지 내 히스토리 네비게이션이 있다.
- isMainFrame boolean - 네비게이션이 메인 프레임에서 발생 중인지 여부
- frame WebFrameMain | null - 이동할 프레임. 프레임이 이미 이동했거나 삭제된 경우 null이 될 수 있다.
- initiator WebFrameMain | null (선택 사항) - 네비게이션을 시작한 프레임. 이는 부모 프레임일 수 있다(예: window.open을 사용한 프레임 이름). 프레임에 의해 시작되지 않은 경우 null이 된다. 또한 이벤트가 발생하기 전에 시작 프레임이 삭제된 경우에도 null이 될 수 있다.
url string Deprecated
isInPlace boolean Deprecated
isMainFrame boolean Deprecated
frameProcessId Integer Deprecated
frameRoutingId Integer Deprecated

네비게이션 중 서버 측 리다이렉트가 발생한 후에 이벤트가 발생한다. 예를 들어 302 리다이렉트가 있을 때 이 이벤트가 발생한다.

이 이벤트는 막을 수 없다. 리다이렉트를 막고 싶다면 위의 will-redirect 이벤트를 확인해야 한다.

이벤트: 'did-navigate'

반환 값:

event Event
url string
httpResponseCode Integer - HTTP가 아닌 네비게이션의 경우 -1
httpStatusText string - HTTP가 아닌 네비게이션의 경우 빈 문자열

메인 프레임의 네비게이션이 완료되었을 때 발생한다.

이 이벤트는 앵커 링크를 클릭하거나 window.location.hash를 업데이트하는 등의 페이지 내 네비게이션에는 발생하지 않는다. 이러한 경우에는 did-navigate-in-page 이벤트를 사용한다.

이벤트: 'did-frame-navigate'

반환값:

event Event
url string
httpResponseCode Integer - HTTP가 아닌 네비게이션의 경우 -1
httpStatusText string - HTTP가 아닌 네비게이션의 경우 빈 문자열
isMainFrame boolean
frameProcessId Integer
frameRoutingId Integer

이 이벤트는 프레임 네비게이션이 완료될 때 발생한다.

앵커 링크를 클릭하거나 window.location.hash를 업데이트하는 등의 페이지 내 네비게이션에서는 이 이벤트가 발생하지 않는다. 이러한 경우에는 did-navigate-in-page 이벤트를 사용해야 한다.

이벤트: 'did-navigate-in-page'

반환값:

event 이벤트
url 문자열
isMainFrame 불리언
frameProcessId 정수
frameRoutingId 정수

이 이벤트는 페이지 내의 어떤 프레임에서 페이지 내 네비게이션이 발생했을 때 발생한다.

페이지 내 네비게이션이 발생하면 페이지의 URL은 변경되지만, 페이지 외부로의 네비게이션은 일어나지 않는다. 이 현상은 앵커 링크를 클릭하거나 DOM의 hashchange 이벤트가 트리거될 때 발생한다.

이벤트: 'will-prevent-unload'

반환값:

event Event

beforeunload 이벤트 핸들러가 페이지 언로드를 취소하려고 할 때 발생한다.

event.preventDefault()를 호출하면 beforeunload 이벤트 핸들러를 무시하고 페이지 언로드를 허용한다.

const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
  const choice = dialog.showMessageBoxSync(win, {
    type: 'question',
    buttons: ['Leave', 'Stay'],
    title: 'Do you want to leave this site?',
    message: 'Changes you made may not be saved.',
    defaultId: 0,
    cancelId: 1
  })
  const leave = (choice === 0)
  if (leave) {
    event.preventDefault()
  }
})

참고: 이 이벤트는 BrowserViews에서도 발생하지만, 실제로는 반영되지 않는다. 이는 명세에 따라 BrowserView의 라이프사이클을 소유하는 BrowserWindow와 연결하지 않기로 결정했기 때문이다.

이벤트: 'render-process-gone'

반환값:

event 이벤트
details RenderProcessGoneDetails

렌더러 프로세스가 예기치 않게 사라질 때 발생한다. 일반적으로 프로세스가 크래시되거나 강제 종료된 경우에 이 이벤트가 발생한다.

이벤트: 'unresponsive'

웹 페이지가 응답하지 않을 때 발생한다.

이벤트: 'responsive'

웹 페이지가 응답하지 않던 상태에서 다시 응답 가능한 상태로 돌아올 때 발생하는 이벤트이다.

이벤트: 'plugin-crashed'

반환값:

event Event
name string
version string

플러그인 프로세스가 충돌했을 때 발생한다.

이벤트: 'destroyed'

webContents가 파괴될 때 발생한다.

이벤트: 'input-event'

반환값:

event Event
inputEvent InputEvent

WebContents에 입력 이벤트가 전송될 때 발생한다. 자세한 내용은 InputEvent를 참고한다.

이벤트: 'before-input-event'

반환 값:

event Event
input Object - 입력 속성.
- type string - keyUp 또는 keyDown 중 하나.
- key string - KeyboardEvent.key와 동일.
- code string - KeyboardEvent.code와 동일.
- isAutoRepeat boolean - KeyboardEvent.repeat와 동일.
- isComposing boolean - KeyboardEvent.isComposing와 동일.
- shift boolean - KeyboardEvent.shiftKey와 동일.
- control boolean - KeyboardEvent.controlKey와 동일.
- alt boolean - KeyboardEvent.altKey와 동일.
- meta boolean - KeyboardEvent.metaKey와 동일.
- location number - KeyboardEvent.location와 동일.
- modifiers string[] - InputEvent.modifiers 참조.

페이지에서 keydown과 keyup 이벤트를 전달하기 전에 발생한다. event.preventDefault를 호출하면 페이지의 keydown/keyup 이벤트와 메뉴 단축키를 막을 수 있다.

메뉴 단축키만 막으려면 setIgnoreMenuShortcuts를 사용한다:

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

win.webContents.on('before-input-event', (event, input) => {
  // 예를 들어, Ctrl/Cmd 키가 눌렸을 때만 애플리케이션 메뉴 키보드 단축키를 활성화한다.
  win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

이벤트: 'enter-html-full-screen'

HTML API에 의해 윈도우가 전체 화면 상태로 전환될 때 발생한다.

이벤트: 'leave-html-full-screen'

이 이벤트는 HTML API에 의해 트리거된 전체 화면 상태에서 윈도우가 벗어날 때 발생한다.

이벤트: 'zoom-changed'

반환 값:

event Event
zoomDirection string - in 또는 out 값을 가질 수 있다.

사용자가 마우스 휠을 사용해 확대/축소 수준을 변경하려고 할 때 발생한다.

이벤트: 'blur'

WebContents가 포커스를 잃을 때 발생한다.

이벤트: 'focus'

WebContents가 포커스를 얻을 때 이벤트가 발생한다.

macOS에서는 포커스가 있다는 것은 WebContents가 윈도우의 첫 번째 응답자가 된다는 것을 의미한다. 따라서 윈도우 간에 포커스를 전환해도 각 윈도우의 첫 번째 응답자가 변경되지 않기 때문에 WebContents의 focus와 blur 이벤트가 발생하지 않는다.

WebContents의 focus와 blur 이벤트는 동일한 윈도우 내에서 다른 WebContents와 BrowserView 간의 포커스 변경을 감지하는 데만 사용해야 한다.

이벤트: 'devtools-open-url'

반환값:

event Event
url string - 클릭하거나 선택한 링크의 URL

DevTools에서 링크를 클릭하거나 컨텍스트 메뉴에서 '새 탭에서 열기'를 선택했을 때 발생한다.

이벤트: 'devtools-search-query'

반환값:

event Event
query string - 검색할 텍스트

컨텍스트 메뉴에서 '검색'을 선택했을 때 발생하는 이벤트이다.

이벤트: 'devtools-opened'

DevTools가 열릴 때 발생하는 이벤트다.

이벤트: 'devtools-closed'

DevTools가 닫힐 때 발생한다.

이벤트: 'devtools-focused'

DevTools가 포커스되거나 열릴 때 발생한다.

이벤트: 'certificate-error'

반환값:

event Event
url string
error string - 에러 코드
certificate Certificate
callback Function
- isTrusted boolean - 인증서가 신뢰할 수 있는지 여부를 나타냄
isMainFrame boolean

url에 대한 certificate 검증에 실패했을 때 발생한다.

사용법은 app의 certificate-error 이벤트와 동일하다.

이벤트: 'select-client-certificate'

반환값:

event Event
url URL
certificateList Certificate[]
callback Function
- certificate Certificate - 주어진 목록에서 선택된 인증서여야 한다.

클라이언트 인증서가 요청될 때 발생한다.

이 이벤트의 사용법은 app의 select-client-certificate 이벤트와 동일하다.

반환값:

event Event
authenticationResponseDetails Object
- url URL
authInfo Object
- isProxy boolean
- scheme string
- host string
- port Integer
- realm string
callback Function
- username string (선택 사항)
- password string (선택 사항)

이 이벤트는 webContents가 기본 인증을 시도할 때 발생한다.

사용법은 app의 login 이벤트와 동일하다.

이벤트: 'found-in-page'

반환값:

event Event
result Object
- requestId Integer
- activeMatchOrdinal Integer - 현재 일치 항목의 위치
- matches Integer - 일치 항목의 총 개수
- selectionArea Rectangle - 첫 번째 일치 항목 영역의 좌표
- finalUpdate boolean

webContents.findInPage 요청에 대한 결과가 준비되면 이 이벤트가 발생한다.

이벤트: 'media-started-playing'

미디어 재생이 시작될 때 발생한다.

이벤트: 'media-paused'

미디어가 일시 정지되거나 재생이 완료되었을 때 발생한다.

Event: 'audio-state-changed'

반환값:

event Event<>
- audible boolean - 하나 이상의 프레임이나 자식 webContents에서 오디오가 재생되고 있으면 true.

미디어가 들리기 시작하거나 들리지 않게 될 때 발생한다.

이벤트: 'did-change-theme-color'

반환값:

event Event
color (string | null) - 테마 색상은 '#rrggbb' 형식으로 제공된다. 테마 색상이 설정되지 않은 경우 null이다.

페이지의 테마 색상이 변경될 때 발생한다. 이 이벤트는 일반적으로 다음과 같은 메타 태그를 만났을 때 발생한다:

<meta name='theme-color' content='#ff0000'>

이벤트: 'update-target-url'

반환 값:

event Event
url string

이 이벤트는 마우스가 링크 위로 이동하거나 키보드로 링크에 포커스가 이동할 때 발생한다.

이벤트: 'cursor-changed'

반환값:

event Event
type string
image NativeImage (선택 사항)
scale Float (선택 사항) - 커스텀 커서의 스케일링 팩터
size Size (선택 사항) - image의 크기
hotspot Point (선택 사항) - 커스텀 커서의 핫스팟 좌표

커서 타입이 변경될 때 발생하는 이벤트다. type 파라미터는 pointer, crosshair, hand, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, m-panning-vertical, m-panning-horizontal, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing, custom, null, drag-drop-none, drag-drop-move, drag-drop-copy, drag-drop-link, ns-no-resize, ew-no-resize, nesw-no-resize, nwse-no-resize, 또는 default가 될 수 있다.

type 파라미터가 custom인 경우, image 파라미터는 커스텀 커서 이미지를 NativeImage 형태로 포함한다. 그리고 scale, size, hotspot 파라미터는 커스텀 커서에 대한 추가 정보를 제공한다.

반환값:

event Event
params Object
- x Integer - x 좌표.
- y Integer - y 좌표.
- frame WebFrameMain | null - 컨텍스트 메뉴가 호출된 프레임. 프레임이 네비게이션 되거나 파괴된 후에 접근하면 null이 될 수 있다.
- linkURL string - 컨텍스트 메뉴가 호출된 노드를 감싸는 링크의 URL.
- linkText string - 링크와 관련된 텍스트. 링크 내용이 이미지인 경우 빈 문자열일 수 있다.
- pageURL string - 컨텍스트 메뉴가 호출된 최상위 페이지의 URL.
- frameURL string - 컨텍스트 메뉴가 호출된 서브프레임의 URL.
- srcURL string - 컨텍스트 메뉴가 호출된 엘리먼트의 소스 URL. 소스 URL이 있는 엘리먼트는 이미지, 오디오, 비디오 등이다.
- mediaType string - 컨텍스트 메뉴가 호출된 노드의 타입. none, image, audio, video, canvas, file, plugin 중 하나가 될 수 있다.
- hasImageContents boolean - 컨텍스트 메뉴가 비어 있지 않은 내용을 가진 이미지에서 호출되었는지 여부.
- isEditable boolean - 컨텍스트가 편집 가능한지 여부.
- selectionText string - 컨텍스트 메뉴가 호출된 선택 영역의 텍스트.
- titleText string - 컨텍스트 메뉴가 호출된 선택 영역의 제목 텍스트.
- altText string - 컨텍스트 메뉴가 호출된 선택 영역의 대체 텍스트.
- suggestedFilename string - 컨텍스트 메뉴의 '링크를 다른 이름으로 저장' 옵션을 통해 파일을 저장할 때 사용할 제안된 파일명.
- selectionRect Rectangle - 문서 공간에서 선택 영역의 좌표를 나타내는 사각형.
- selectionStartOffset number - 선택 텍스트의 시작 위치.
- referrerPolicy Referrer - 메뉴가 호출된 프레임의 리퍼러 정책.
- misspelledWord string - 커서 아래에 있는 잘못된 단어, 있다면.
- dictionarySuggestions string[] - misspelledWord를 대체하기 위해 사용자에게 보여줄 제안 단어 배열. 잘못된 단어가 있고 맞춤법 검사기가 활성화된 경우에만 사용 가능.
- frameCharset string - 메뉴가 호출된 프레임의 문자 인코딩.
- formControlType string - 컨텍스트 메뉴가 호출된 소스. 가능한 값은 none, button-button, field-set, input-button, input-checkbox, input-color, input-date, input-datetime-local, input-email, input-file, input-hidden, input-image, input-month, input-number, input-password, input-radio, input-range, input-reset, input-search, input-submit, input-telephone, input-text, input-time, input-url, input-week, output, reset-button, select-list, select-list, select-multiple, select-one, submit-button, text-area 등이다.
- spellcheckEnabled boolean - 컨텍스트가 편집 가능한 경우, 맞춤법 검사가 활성화되었는지 여부.
- menuSourceType string - 컨텍스트 메뉴를 호출한 입력 소스. none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, adjustSelectionReset 중 하나가 될 수 있다.
- mediaFlags Object - 컨텍스트 메뉴가 호출된 미디어 엘리먼트의 플래그.
  - inError boolean - 미디어 엘리먼트가 오류 상태인지 여부.
  - isPaused boolean - 미디어 엘리먼트가 일시 정지되었는지 여부.
  - isMuted boolean - 미디어 엘리먼트가 음소거되었는지 여부.
  - hasAudio boolean - 미디어 엘리먼트에 오디오가 있는지 여부.
  - isLooping boolean - 미디어 엘리먼트가 반복 재생 중인지 여부.
  - isControlsVisible boolean - 미디어 엘리먼트의 컨트롤이 보이는지 여부.
  - canToggleControls boolean - 미디어 엘리먼트의 컨트롤을 토글할 수 있는지 여부.
  - canPrint boolean - 미디어 엘리먼트를 인쇄할 수 있는지 여부.
  - canSave boolean - 미디어 엘리먼트를 다운로드할 수 있는지 여부.
  - canShowPictureInPicture boolean - 미디어 엘리먼트가 picture-in-picture를 보여줄 수 있는지 여부.
  - isShowingPictureInPicture boolean - 미디어 엘리먼트가 현재 picture-in-picture를 보여주고 있는지 여부.
  - canRotate boolean - 미디어 엘리먼트를 회전할 수 있는지 여부.
  - canLoop boolean - 미디어 엘리먼트를 반복할 수 있는지 여부.
- editFlags Object - 랜더러가 해당 작업을 수행할 수 있다고 판단하는지 여부를 나타내는 플래그.
  - canUndo boolean - 랜더러가 실행 취소를 할 수 있다고 판단하는지 여부.
  - canRedo boolean - 랜더러가 다시 실행을 할 수 있다고 판단하는지 여부.
  - canCut boolean - 랜더러가 잘라내기를 할 수 있다고 판단하는지 여부.
  - canCopy boolean - 랜더러가 복사를 할 수 있다고 판단하는지 여부.
  - canPaste boolean - 랜더러가 붙여넣기를 할 수 있다고 판단하는지 여부.
  - canDelete boolean - 랜더러가 삭제를 할 수 있다고 판단하는지 여부.
  - canSelectAll boolean - 랜더러가 전체 선택을 할 수 있다고 판단하는지 여부.
  - canEditRichly boolean - 랜더러가 텍스트를 풍부하게 편집할 수 있다고 판단하는지 여부.

처리해야 할 새로운 컨텍스트 메뉴가 있을 때 발생한다.

이벤트: 'select-bluetooth-device'

반환 값:

event Event
devices BluetoothDevice[]
callback Function
- deviceId string

navigator.bluetooth.requestDevice 호출 시 블루투스 장치를 선택해야 할 때 이 이벤트가 발생한다. callback은 선택할 장치의 deviceId와 함께 호출해야 한다. callback에 빈 문자열을 전달하면 요청을 취소한다.

이 이벤트에 대한 리스너를 추가하지 않거나, 이벤트를 처리할 때 event.preventDefault를 호출하지 않으면, 첫 번째로 사용 가능한 장치가 자동으로 선택된다.

블루투스의 특성상, navigator.bluetooth.requestDevice 호출 시 장치를 스캔하는 데 시간이 걸릴 수 있으며, callback이 장치 ID나 빈 문자열과 함께 호출될 때까지 select-bluetooth-device 이벤트가 여러 번 발생할 수 있다.

main.js
const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    const result = deviceList.find((device) => {
      return device.deviceName === 'test'
    })
    if (!result) {
      // 장치를 찾지 못했으므로 더 오래 기다리거나(예: 장치가 켜질 때까지)
      // 빈 문자열과 함께 callback을 호출해 요청을 취소한다.
      callback('')
    } else {
      callback(result.deviceId)
    }
  })
})

이벤트: 'paint'

반환값:

details Event<>
- texture OffscreenSharedTexture (선택 사항) 실험적 - webPreferences.offscreen.useSharedTexture가 true일 때 프레임의 GPU 공유 텍스처.
dirtyRect Rectangle
image NativeImage - 전체 프레임의 이미지 데이터.

새로운 프레임이 생성될 때 발생한다. 버퍼에는 변경된 영역만 전달된다.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
  // updateBitmap(dirty, image.getBitmap())
})
win.loadURL('https://github.com')

공유 텍스처 기능(webPreferences.offscreen.useSharedTexture를 true로 설정)을 사용하면, CPU와 GPU 메모리 간 데이터 복사 오버헤드 없이 Chromium의 하드웨어 가속 지원을 통해 텍스처 핸들을 외부 렌더링 파이프라인에 전달할 수 있다. 이 기능은 고성능 렌더링 시나리오에 유용하다.

동시에 존재할 수 있는 텍스처의 수는 제한적이므로, 텍스처 사용을 마치면 texture.release()를 가능한 한 빨리 호출해야 한다. 텍스처 라이프사이클을 직접 관리함으로써 texture.textureInfo를 IPC를 통해 다른 프로세스에 안전하게 전달할 수 있다.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } })
win.webContents.on('paint', async (e, dirty, image) => {
  if (e.texture) {
    // 라이프사이클을 직접 관리하면 비동기 핸들러에서 이벤트를 처리하거나 `e.texture.textureInfo`를 다른 프로세스에 전달할 수 있다.
    // (`e.texture`가 아닌 `e.texture.release` 함수는 IPC를 통해 전달할 수 없다.)
    await new Promise(resolve => setTimeout(resolve, 50))

    // 네이티브 텍스처 핸들을 네이티브 코드로 전달하여 렌더링 파이프라인에 임포트할 수 있다.
    // 예시: https://github.com/electron/electron/tree/main/spec/fixtures/native-addon/osr-gpu
    // importTextureHandle(dirty, e.texture.textureInfo)

    // 기본 프레임 풀이 고갈되기 전에 가능한 한 빨리 `e.texture.release()`를 호출해야 한다.
    e.texture.release()
  }
})
win.loadURL('https://github.com')

이벤트: 'devtools-reload-page'

devtools 윈도우가 webContents에 페이지를 다시 로드하도록 지시할 때 발생한다.

이벤트: 'will-attach-webview'

반환값:

event Event
webPreferences WebPreferences - 게스트 페이지에서 사용할 웹 환경 설정. 이 객체를 수정해 게스트 페이지의 설정을 조정할 수 있다.
params Record<string, string> - src URL과 같은 다른 <webview> 매개변수. 이 객체를 수정해 게스트 페이지의 매개변수를 조정할 수 있다.

이 이벤트는 <webview>의 웹 콘텐츠가 현재 웹 콘텐츠에 첨부될 때 발생한다. event.preventDefault()를 호출하면 게스트 페이지가 파괴된다.

이 이벤트는 <webview>가 로드되기 전에 webContents의 webPreferences를 구성하는 데 사용할 수 있다. 또한 <webview> 속성으로 설정할 수 없는 설정을 지정할 수 있는 기능을 제공한다.

이벤트: 'did-attach-webview'

반환값:

event Event
webContents WebContents - <webview>가 사용하는 게스트 웹 콘텐츠

이 이벤트는 <webview>가 현재 웹 콘텐츠에 연결되었을 때 발생한다.

이벤트: 'console-message'

반환 값:

event Event
level Integer - 로그 레벨. 0부터 3까지의 값을 가지며, 각각 verbose, info, warning, error에 해당한다.
message string - 실제 콘솔 메시지
line Integer - 이 콘솔 메시지를 발생시킨 소스 코드의 라인 번호
sourceId string

연결된 윈도우에서 콘솔 메시지를 기록할 때 발생한다.

이벤트: 'preload-error'

반환값:

event Event
preloadPath string
error Error

프리로드 스크립트 preloadPath에서 처리되지 않은 예외 error가 발생했을 때 이벤트가 발생한다.

이벤트: 'ipc-message'

반환값:

event IpcMainEvent
channel string
...args any[]

렌더러 프로세스가 ipcRenderer.send()를 통해 비동기 메시지를 보낼 때 발생한다.

이 WebContents에서 보낸 IPC 메시지에 응답하기 위해 IpcMain과 유사한 인터페이스를 제공하는 webContents.ipc도 참고한다.

이벤트: 'ipc-message-sync'

반환값:

event IpcMainEvent
channel string
...args any[]

렌더러 프로세스가 ipcRenderer.sendSync()를 통해 동기식 메시지를 보낼 때 발생한다.

이 WebContents에서 보낸 IPC 메시지에 응답하기 위한 IpcMain과 유사한 인터페이스를 제공하는 webContents.ipc도 참고한다.

이벤트: 'preferred-size-changed'

반환 값:

event Event
preferredSize Size - 스크롤 없이 문서 레이아웃을 포함하는 데 필요한 최소 크기

WebContents의 선호 크기가 변경될 때 발생한다.

이 이벤트는 webPreferences에서 enablePreferredSizeMode가 true로 설정된 경우에만 발생한다.

이벤트: 'frame-created'

반환값:

event Event
details Object
- frame WebFrameMain | null - 생성된 프레임. 프레임이 네비게이션 되거나 파괴된 후에 접근하면 null이 될 수 있다.

이 이벤트는 mainFrame, <iframe>, 또는 중첩된 <iframe>이 페이지 내에서 로드될 때 발생한다.

인스턴스 메서드

`contents.loadURL(url[, options])`

url string
options Object (선택 사항)
- httpReferrer (string | Referrer) (선택 사항) - HTTP 리퍼러 URL.
- userAgent string (선택 사항) - 요청을 보내는 사용자 에이전트.
- extraHeaders string (선택 사항) - "\n"으로 구분된 추가 헤더.
- postData (UploadRawData | UploadFile)[] (선택 사항)
- baseURLForDataURL string (선택 사항) - 데이터 URL로 로드될 파일의 기본 URL (경로 구분자 포함). 이 옵션은 지정된 url이 데이터 URL이고 다른 파일을 로드해야 할 때만 필요하다.

반환 값: Promise<void> - 페이지 로드가 완료되면 Promise가 해결되고 (did-finish-load 참조), 페이지 로드에 실패하면 Promise가 거부된다 (did-fail-load 참조). 처리되지 않은 거부 오류를 방지하기 위해 기본적으로 noop 거부 핸들러가 연결되어 있다.

윈도우에 url을 로드한다. url은 반드시 프로토콜 접두사(예: http:// 또는 file://)를 포함해야 한다. HTTP 캐시를 우회하여 로드하려면 pragma 헤더를 사용한다.

const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)

`contents.loadFile(filePath[, options])`

filePath string
options Object (선택 사항)
- query Record<string, string> (선택 사항) - url.format()에 전달된다.
- search string (선택 사항) - url.format()에 전달된다.
- hash string (선택 사항) - url.format()에 전달된다.

Promise<void>를 반환한다. 이 Promise는 페이지 로딩이 완료되면 해결되고(did-finish-load 참조), 페이지 로딩이 실패하면 거부된다(did-fail-load 참조).

윈도우에서 주어진 파일을 로드한다. filePath는 애플리케이션 루트를 기준으로 한 HTML 파일의 경로여야 한다. 예를 들어 다음과 같은 애플리케이션 구조가 있다고 가정해 보자:

| root
| - package.json
| - src
|   - main.js
|   - index.html

이 경우 다음과 같은 코드를 사용할 수 있다:

const win = new BrowserWindow()
win.loadFile('src/index.html')

`contents.downloadURL(url[, options])`

url string
options Object (선택 사항)
- headers Record<string, string> (선택 사항) - HTTP 요청 헤더.

이 메서드는 네비게이션 없이 url에 있는 리소스를 다운로드한다. session의 will-download 이벤트가 트리거된다.

`contents.getURL()`

string 타입의 값을 반환한다. 현재 웹 페이지의 URL을 나타낸다.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
  const currentURL = win.webContents.getURL()
  console.log(currentURL)
})

`contents.getTitle()`

string 타입을 반환한다. 현재 웹 페이지의 제목을 나타낸다.

`contents.isDestroyed()`

boolean을 반환한다. 웹 페이지가 파괴되었는지 여부를 나타낸다.

`contents.close([opts])`

opts Object (선택 사항)
- waitForBeforeUnload boolean - true로 설정하면 페이지를 닫기 전에 beforeunload 이벤트를 발생시킨다. 페이지가 언로드를 막으면 WebContents는 닫히지 않는다. 페이지가 언로드 방지를 요청하면 will-prevent-unload 이벤트가 발생한다.

페이지를 닫는다. 웹 콘텐츠가 window.close()를 호출한 것과 동일한 효과를 가진다.

페이지가 성공적으로 닫히면(즉, 페이지가 언로드를 막지 않거나 waitForBeforeUnload가 false이거나 지정되지 않은 경우), WebContents는 제거되고 더 이상 사용할 수 없게 된다. destroyed 이벤트가 발생한다.

contents.focus()는 웹 페이지에 포커스를 설정한다.

`contents.isFocused()`

boolean을 반환한다. 웹 페이지가 현재 포커스 상태인지 여부를 나타낸다.

`contents.isLoading()`

boolean 타입을 반환한다. 웹 페이지가 아직 리소스를 로드 중인지 여부를 나타낸다.

`contents.isLoadingMainFrame()`

boolean 타입을 반환한다. 메인 프레임(내부의 iframe이나 다른 프레임이 아닌)이 여전히 로딩 중인지 여부를 나타낸다.

`contents.isWaitingForResponse()`

boolean을 반환한다. 웹 페이지가 메인 리소스로부터 첫 응답을 기다리고 있는지 여부를 나타낸다.

`contents.stop()`

진행 중인 모든 네비게이션을 중지한다.

`contents.reload()`

현재 웹 페이지를 새로고침한다.

`contents.reloadIgnoringCache()`

현재 페이지를 다시 로드하고 캐시를 무시한다.

`contents.canGoBack()` 더 이상 사용되지 않음

History

Version(s)	Changes
None	API DEPRECATED

boolean을 반환한다. 브라우저가 이전 웹 페이지로 돌아갈 수 있는지 여부를 나타낸다.

더 이상 사용되지 않음: 새로운 contents.navigationHistory.canGoBack API를 사용해야 한다.

`contents.canGoForward()` 사용 중단됨

History

Version(s)	Changes
None	API DEPRECATED

boolean을 반환한다. 브라우저가 다음 웹 페이지로 이동할 수 있는지 여부를 나타낸다.

사용 중단됨: 새로운 contents.navigationHistory.canGoForward API를 사용해야 한다.

`contents.canGoToOffset(offset)` Deprecated

History

Version(s)	Changes
None	API DEPRECATED

offset Integer

boolean을 반환한다 - 웹 페이지가 offset으로 이동할 수 있는지 여부를 나타낸다.

Deprecated: 새로운 contents.navigationHistory.canGoToOffset API를 사용해야 한다.

`contents.clearHistory()` 사용 중단됨

History

Version(s)	Changes
None	API DEPRECATED

네비게이션 히스토리를 지운다.

사용 중단됨: 새로운 contents.navigationHistory.clear API를 사용해야 한다.

`contents.goBack()` Deprecated

History

Version(s)	Changes
None	API DEPRECATED

브라우저를 이전 웹 페이지로 이동시킨다.

Deprecated: 새로운 contents.navigationHistory.goBack API를 사용해야 한다.

`contents.goForward()` 사용 중단됨

YAML history deprecated:

pr-url: https://github.com/electron/electron/pull/41752 breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents

브라우저가 웹 페이지를 앞으로 이동하도록 한다.

사용 중단됨: 새로운 contents.navigationHistory.goForward API를 사용해야 한다.

`contents.goToIndex(index)` Deprecated

History

Version(s)	Changes
None	API DEPRECATED

index Integer

브라우저를 지정된 절대 웹 페이지 인덱스로 이동시킨다.

Deprecated: 새로운 contents.navigationHistory.goToIndex API를 사용해야 한다.

`contents.goToOffset(offset)` Deprecated

History

Version(s)	Changes
None	API DEPRECATED

offset Integer

현재 항목에서 지정된 오프셋으로 이동한다.

Deprecated: 새로운 contents.navigationHistory.goToOffset API를 사용해야 한다.

contents.isCrashed()는 렌더러 프로세스가 크래시되었는지 여부를 boolean 값으로 반환한다.

`contents.forcefullyCrashRenderer()`

이 메서드는 현재 webContents를 호스팅하는 렌더러 프로세스를 강제로 종료한다. 이로 인해 render-process-gone 이벤트가 reason=killed 또는 reason=crashed와 함께 발생한다. 일부 webContents는 렌더러 프로세스를 공유하므로, 이 메서드를 호출하면 다른 webContents의 호스트 프로세스도 함께 종료될 수 있다.

이 메서드를 호출한 직후 reload()를 호출하면, 리로드가 새로운 프로세스에서 강제로 실행된다. 이 방법은 프로세스가 불안정하거나 사용할 수 없는 상태일 때, 예를 들어 unresponsive 이벤트로부터 복구하기 위해 사용한다.

const win = new BrowserWindow()

win.webContents.on('unresponsive', async () => {
  const { response } = await dialog.showMessageBox({
    message: 'App X has become unresponsive',
    title: 'Do you want to try forcefully reloading the app?',
    buttons: ['OK', 'Cancel'],
    cancelId: 1
  })
  if (response === 0) {
    win.webContents.forcefullyCrashRenderer()
    win.webContents.reload()
  }
})

`contents.setUserAgent(userAgent)`

userAgent string

현재 웹 페이지의 사용자 에이전트를 재정의한다.

`contents.getUserAgent()`

string 타입을 반환한다. 이 웹 페이지의 사용자 에이전트(user agent)를 나타낸다.

`contents.insertCSS(css[, options])`

css string
options Object (선택 사항)
- cssOrigin string (선택 사항) - 'user' 또는 'author' 값을 가질 수 있다. 삽입된 스타일시트의 캐스케이드 오리진을 설정한다. 기본값은 'author'이다.

반환 값: Promise<string> - 삽입된 CSS의 고유 키를 반환하는 Promise. 이 키는 나중에 contents.removeInsertedCSS(key)를 통해 CSS를 제거하는 데 사용할 수 있다.

현재 웹 페이지에 CSS를 주입하고, 삽입된 스타일시트에 대한 고유 키를 반환한다.

const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
  win.webContents.insertCSS('html, body { background-color: #f00; }')
})

`contents.removeInsertedCSS(key)`

key string

Promise<void>를 반환한다. CSS 제거가 성공하면 resolve된다.

현재 웹 페이지에서 삽입된 CSS를 제거한다. 스타일시트는 contents.insertCSS(css)에서 반환된 키로 식별된다.

const win = new BrowserWindow()

win.webContents.on('did-finish-load', async () => {
  const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
  win.webContents.removeInsertedCSS(key)
})

`contents.executeJavaScript(code[, userGesture])`

code string
userGesture boolean (선택 사항) - 기본값은 false.

반환값: Promise<any> - 실행된 코드의 결과로 resolve되거나, 코드의 결과가 rejected Promise인 경우 reject되는 Promise.

페이지에서 code를 실행한다.

브라우저 윈도우에서 requestFullScreen과 같은 일부 HTML API는 사용자의 제스처가 있어야만 호출할 수 있다. userGesture를 true로 설정하면 이 제한을 해제할 수 있다.

코드 실행은 웹 페이지가 로딩을 멈출 때까지 중단된다.

const win = new BrowserWindow()

win.webContents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
  .then((result) => {
    console.log(result) // fetch 호출의 JSON 객체가 출력된다
  })

`contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])`

worldId Integer - 자바스크립트를 실행할 세계의 ID. 0은 기본 세계이며, 999는 Electron의 contextIsolation 기능에서 사용하는 세계이다. 여기에는 어떤 정수든 입력할 수 있다.
scripts WebSource[]
userGesture boolean (선택 사항) - 기본값은 false.

Promise<any>를 반환한다. 실행된 코드의 결과로 이행되거나, 코드의 결과가 거부된 Promise인 경우 거부된다.

executeJavaScript와 유사하게 동작하지만, scripts를 격리된 컨텍스트에서 평가한다.

`contents.setIgnoreMenuShortcuts(ignore)`

ignore boolean

이 웹 콘텐츠가 포커스 상태일 때 애플리케이션 메뉴 단축키를 무시한다.

`contents.setWindowOpenHandler(handler)`

handler Function<WindowOpenHandlerResponse>
- details Object
  - url string - window.open()에 전달된 URL의 해석된 버전. 예를 들어 window.open('foo')로 윈도우를 열면 https://the-origin/the/current/path/foo와 같은 URL이 생성된다.
  - frameName string - window.open()에 제공된 윈도우의 이름.
  - features string - window.open()에 제공된 윈도우 기능의 쉼표로 구분된 목록.
  - disposition string - default, foreground-tab, background-tab, new-window, other 중 하나.
  - referrer Referrer - 새 윈도우에 전달될 리퍼러. 리퍼러 정책에 따라 Referer 헤더가 전송될 수도 있고, 전송되지 않을 수도 있다.
  - postBody PostBody (선택 사항) - 새 윈도우에 전송될 POST 데이터와 함께 설정될 적절한 헤더. 전송할 POST 데이터가 없으면 값은 null이 된다. target=_blank로 설정된 폼에 의해 윈도우가 생성될 때만 정의된다.
Returns WindowOpenHandlerResponse - { action: 'deny' }로 설정하면 새 윈도우 생성을 취소한다. { action: 'allow' }로 설정하면 새 윈도우 생성을 허용한다. 인식할 수 없는 값(예: null, undefined, 또는 'action' 값이 없는 객체)을 반환하면 콘솔에 오류가 발생하고 {action: 'deny'}를 반환한 것과 동일한 효과가 발생한다.

렌더러가 새 윈도우를 요청할 때 호출된다. 예를 들어 window.open(), target="_blank"가 설정된 링크, 링크를 Shift+클릭하거나 <form target="_blank">로 폼을 제출할 때 호출된다. 자세한 내용과 did-create-window와 함께 사용하는 방법은 window.open()을 참조한다.

새 BrowserWindow 생성 과정을 커스텀화하여 메인 윈도우에 BrowserView를 부착하는 예제:

const { BrowserView, BrowserWindow } = require('electron')

const mainWindow = new BrowserWindow()

mainWindow.webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    createWindow: (options) => {
      const browserView = new BrowserView(options)
      mainWindow.addBrowserView(browserView)
      browserView.setBounds({ x: 0, y: 0, width: 640, height: 480 })
      return browserView.webContents
    }
  }
})

`contents.setAudioMuted(muted)`

muted boolean

현재 웹 페이지의 오디오를 음소거한다.

`contents.isAudioMuted()`

boolean을 반환한다. 해당 페이지가 음소거 상태인지 여부를 나타낸다.

`contents.isCurrentlyAudible()`

boolean을 반환한다. 현재 오디오가 재생 중인지 여부를 나타낸다.

`contents.setZoomFactor(factor)`

factor Double - 확대/축소 비율; 기본값은 1.0이다.

지정한 비율로 확대/축소 비율을 변경한다. 확대/축소 비율은 확대 비율을 100으로 나눈 값이므로, 300%는 3.0이 된다.

비율은 반드시 0.0보다 커야 한다.

`contents.getZoomFactor()`

number 타입의 현재 줌 배율을 반환한다.

`contents.setZoomLevel(level)`

level number - 줌 레벨

지정된 줌 레벨로 변경한다. 원본 크기는 0이며, 0보다 큰 값은 20%씩 확대되고, 작은 값은 20%씩 축소된다. 기본 제한은 원본 크기의 300%와 50%이다. 이 계산 공식은 scale := 1.2 ^ level이다.

참고: Chromium 수준의 줌 정책은 동일 출처(same-origin)를 기준으로 한다. 즉, 특정 도메인의 줌 레벨은 동일한 도메인의 모든 윈도우 인스턴스에 전파된다. 윈도우 URL을 다르게 설정하면 윈도우별로 줌이 작동한다.

`contents.getZoomLevel()`

number 타입의 값을 반환한다. 현재의 줌 레벨을 나타낸다.

`contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)`

minimumLevel number
maximumLevel number

Promise<void>를 반환한다.

핀치 투 줌의 최소 및 최대 줌 레벨을 설정한다.

참고: Electron에서는 기본적으로 시각적 줌이 비활성화되어 있다. 다시 활성화하려면 다음 코드를 호출한다:
const win = new BrowserWindow()
win.webContents.setVisualZoomLevelLimits(1, 3)

`contents.undo()`

웹 페이지에서 편집 명령어 undo를 실행한다.

`contents.redo()`

웹 페이지에서 편집 명령어 redo를 실행한다.

`contents.cut()`

웹 페이지에서 편집 커맨드 cut을 실행한다.

`contents.copy()`

웹 페이지에서 copy 편집 커맨드를 실행한다.

`contents.centerSelection()`

현재 웹 페이지에서 선택된 텍스트를 가운데 정렬한다.

`contents.copyImageAt(x, y)`

x 정수
y 정수

주어진 위치에 있는 이미지를 클립보드로 복사한다.

`contents.paste()`

웹 페이지에서 paste 편집 커맨드를 실행한다.

`contents.pasteAndMatchStyle()`

웹 페이지에서 pasteAndMatchStyle 편집 명령을 실행한다.

`contents.delete()`

웹 페이지에서 delete 편집 명령을 실행한다.

`contents.selectAll()`

웹 페이지에서 selectAll 편집 커맨드를 실행한다.

`contents.unselect()`

웹 페이지에서 unselect 편집 커맨드를 실행한다.

`contents.scrollToTop()`

현재 webContents의 맨 위로 스크롤한다.

`contents.scrollToBottom()`

현재 webContents의 맨 아래로 스크롤한다.

`contents.adjustSelection(options)`

options 객체
- start 숫자 (선택 사항) - 현재 선택 영역의 시작 인덱스를 이동할 양
- end 숫자 (선택 사항) - 현재 선택 영역의 끝 인덱스를 이동할 양

포커스된 프레임 내에서 현재 텍스트 선택 영역의 시작점과 끝점을 지정된 양만큼 조정한다. 음수 값을 사용하면 선택 영역이 문서의 시작 부분으로 이동하고, 양수 값을 사용하면 선택 영역이 문서의 끝 부분으로 이동한다.

예제:

const win = new BrowserWindow()

// 선택 영역의 시작점을 1글자 앞으로 이동하고,
// 선택 영역의 끝점을 5글자 앞으로 이동한다.
win.webContents.adjustSelection({ start: 1, end: 5 })

// 선택 영역의 시작점을 2글자 앞으로 이동하고,
// 선택 영역의 끝점을 3글자 뒤로 이동한다.
win.webContents.adjustSelection({ start: 2, end: -3 })

win.webContents.adjustSelection({ start: 1, end: 5 }) 호출 시

이후:

`contents.replace(text)`

text 문자열

웹 페이지에서 replace 편집 커맨드를 실행한다.

`contents.replaceMisspelling(text)`

text string

웹 페이지에서 replaceMisspelling 편집 커맨드를 실행한다.

`contents.insertText(text)`

text string

Promise<void>를 반환한다.

포커스된 엘리먼트에 text를 삽입한다.

`contents.findInPage(text[, options])`

text string - 검색할 내용으로, 비어 있으면 안 된다.
options Object (선택 사항)
- forward boolean (선택 사항) - 앞으로 검색할지 뒤로 검색할지 결정한다. 기본값은 true다.
- findNext boolean (선택 사항) - 이 요청으로 새로운 텍스트 검색 세션을 시작할지 여부를 결정한다. 초기 요청에는 true를, 후속 요청에는 false를 사용한다. 기본값은 false다.
- matchCase boolean (선택 사항) - 검색 시 대소문자를 구분할지 여부를 결정한다. 기본값은 false다.

Returns Integer - 요청에 사용된 요청 ID를 반환한다.

웹 페이지에서 text와 일치하는 모든 항목을 찾기 위한 요청을 시작한다. 요청 결과는 found-in-page 이벤트를 구독하여 얻을 수 있다.

`contents.stopFindInPage(action)`

action string - webContents.findInPage 요청을 종료할 때 수행할 동작을 지정한다.
- clearSelection - 선택 영역을 지운다.
- keepSelection - 선택 영역을 일반 선택으로 변환한다.
- activateSelection - 선택된 노드에 포커스를 맞추고 클릭한다.

제공된 action으로 webContents에 대한 모든 findInPage 요청을 중지한다.

const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
  if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})

const requestId = win.webContents.findInPage('api')
console.log(requestId)

`contents.capturePage([rect, opts])`

rect Rectangle (선택 사항) - 캡처할 페이지의 영역을 지정한다.
opts Object (선택 사항)
- stayHidden boolean (선택 사항) - 페이지를 보이지 않게 유지한다. 기본값은 false이다.
- stayAwake boolean (선택 사항) - 시스템이 슬립 모드로 들어가지 않게 유지한다. 기본값은 false이다.

Promise<NativeImage>를 반환한다 - NativeImage로 resolve된다.

rect 영역 내의 페이지 스냅샷을 캡처한다. rect를 생략하면 전체 보이는 페이지를 캡처한다. 브라우저 윈도우가 숨겨져 있고 캡처 카운트가 0이 아닌 경우 페이지는 보이는 것으로 간주된다. 페이지를 숨겨진 상태로 유지하려면 stayHidden을 true로 설정해야 한다.

`contents.isBeingCaptured()`

boolean 값을 반환한다. 이 메서드는 현재 페이지가 캡처 중인지 여부를 나타낸다. 캡처 카운트가 0보다 크면 true를 반환한다.

`contents.getPrintersAsync()`

시스템 프린터 목록을 가져온다.

반환 값
Promise<PrinterInfo[]> - PrinterInfo[]로 해소된다.

`contents.print([options], [callback])`

options Object (선택 사항)
- silent boolean (선택 사항) - 사용자에게 프린트 설정을 묻지 않는다. 기본값은 false.
- printBackground boolean (선택 사항) - 웹 페이지의 배경색과 이미지를 출력한다. 기본값은 false.
- deviceName string (선택 사항) - 사용할 프린터 장치 이름을 설정한다. 시스템에서 정의된 이름을 사용해야 하며, 'Brother QL-820NWB'와 같은 친숙한 이름이 아닌 'Brother_QL_820NWB'와 같은 이름을 사용한다.
- color boolean (선택 사항) - 출력할 웹 페이지를 컬러로 할지 흑백으로 할지 설정한다. 기본값은 true.
- margins Object (선택 사항)
  - marginType string (선택 사항) - default, none, printableArea, custom 중 하나를 선택할 수 있다. custom을 선택한 경우 top, bottom, left, right 값을 추가로 지정해야 한다.
  - top number (선택 사항) - 출력할 웹 페이지의 상단 마진을 픽셀 단위로 설정한다.
  - bottom number (선택 사항) - 출력할 웹 페이지의 하단 마진을 픽셀 단위로 설정한다.
  - left number (선택 사항) - 출력할 웹 페이지의 왼쪽 마진을 픽셀 단위로 설정한다.
  - right number (선택 사항) - 출력할 웹 페이지의 오른쪽 마진을 픽셀 단위로 설정한다.
- landscape boolean (선택 사항) - 웹 페이지를 가로 모드로 출력할지 설정한다. 기본값은 false.
- scaleFactor number (선택 사항) - 웹 페이지의 스케일 팩터를 설정한다.
- pagesPerSheet number (선택 사항) - 한 장의 종이에 출력할 페이지 수를 설정한다.
- collate boolean (선택 사항) - 웹 페이지를 순서대로 정렬하여 출력할지 설정한다.
- copies number (선택 사항) - 출력할 웹 페이지의 복사본 수를 설정한다.
- pageRanges Object[] (선택 사항) - 출력할 페이지 범위를 설정한다. macOS에서는 하나의 범위만 적용된다.
  - from number - 출력할 첫 페이지의 인덱스 (0부터 시작).
  - to number - 출력할 마지막 페이지의 인덱스 (포함, 0부터 시작).
- duplexMode string (선택 사항) - 출력할 웹 페이지의 양면 인쇄 모드를 설정한다. simplex, shortEdge, longEdge 중 하나를 선택할 수 있다.
- dpi Record<string, number> (선택 사항)
  - horizontal number (선택 사항) - 수평 해상도 (DPI).
  - vertical number (선택 사항) - 수직 해상도 (DPI).
- header string (선택 사항) - 페이지 헤더로 출력할 문자열.
- footer string (선택 사항) - 페이지 푸터로 출력할 문자열.
- pageSize string | Size (선택 사항) - 출력할 문서의 페이지 크기를 지정한다. A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid 또는 height와 width를 포함한 객체를 사용할 수 있다.
callback Function (선택 사항)
- success boolean - 프린트 호출의 성공 여부를 나타낸다.
- failureReason string - 프린트가 실패한 경우 반환되는 오류 설명.

커스텀 pageSize를 전달하면 Chromium은 width_microns와 height_microns에 대한 플랫폼별 최소값을 검증하려고 시도한다. 너비와 높이는 최소 353 마이크론이어야 하며, 일부 운영체제에서는 더 높을 수 있다.

윈도우의 웹 페이지를 출력한다. silent가 true로 설정된 경우, deviceName이 비어 있으면 Electron은 시스템의 기본 프린터와 기본 프린트 설정을 사용한다.

page-break-before: always; CSS 스타일을 사용하면 새로운 페이지로 강제로 출력할 수 있다.

예제 사용법:

const win = new BrowserWindow()
const options = {
  silent: true,
  deviceName: 'My-Printer',
  pageRanges: [{
    from: 0,
    to: 1
  }]
}
win.webContents.print(options, (success, errorType) => {
  if (!success) console.log(errorType)
})

`contents.printToPDF(options)`

options Object
- landscape boolean (선택 사항) - 용지 방향. 가로 방향은 true, 세로 방향은 false. 기본값은 false.
- displayHeaderFooter boolean (선택 사항) - 헤더와 푸터를 표시할지 여부. 기본값은 false.
- printBackground boolean (선택 사항) - 배경 그래픽을 출력할지 여부. 기본값은 false.
- scale number (선택 사항) - 웹페이지 렌더링의 축척 비율. 기본값은 1.
- pageSize string | Size (선택 사항) - 생성된 PDF의 페이지 크기 지정. A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid, Ledger 중 하나 또는 height와 width를 인치 단위로 포함한 객체. 기본값은 Letter.
- margins Object (선택 사항)
  - top number (선택 사항) - 상단 마진 (인치). 기본값은 1cm (~0.4인치).
  - bottom number (선택 사항) - 하단 마진 (인치). 기본값은 1cm (~0.4인치).
  - left number (선택 사항) - 좌측 마진 (인치). 기본값은 1cm (~0.4인치).
  - right number (선택 사항) - 우측 마진 (인치). 기본값은 1cm (~0.4인치).
- pageRanges string (선택 사항) - 출력할 페이지 범위 (예: '1-5, 8, 11-13'). 기본값은 빈 문자열로, 모든 페이지를 출력.
- headerTemplate string (선택 사항) - 프린트 헤더를 위한 HTML 템플릿. 유효한 HTML 마크업이어야 하며, 다음 클래스를 사용해 프린트 값을 주입: date (포맷된 프린트 날짜), title (문서 제목), url (문서 위치), pageNumber (현재 페이지 번호), totalPages (문서의 총 페이지 수). 예: <span class=title></span>는 제목을 포함한 span을 생성.
- footerTemplate string (선택 사항) - 프린트 푸터를 위한 HTML 템플릿. headerTemplate와 동일한 형식 사용.
- preferCSSPageSize boolean (선택 사항) - CSS에 정의된 페이지 크기를 우선할지 여부. 기본값은 false, 이 경우 콘텐츠가 용지 크기에 맞게 조정.
- generateTaggedPDF boolean (선택 사항) 실험적 - 태그가 지정된 (접근 가능한) PDF를 생성할지 여부. 기본값은 false. 이 속성은 실험적이므로 생성된 PDF가 PDF/UA 및 WCAG 표준을 완전히 준수하지 않을 수 있음.
- generateDocumentOutline boolean (선택 사항) 실험적 - 콘텐츠 헤더에서 PDF 문서 개요를 생성할지 여부. 기본값은 false.

반환값 Promise<Buffer> - 생성된 PDF 데이터로 이행.

윈도우의 웹 페이지를 PDF로 출력.

웹 페이지에서 @page CSS at-rule을 사용할 경우 landscape는 무시.

webContents.printToPDF 예제:

const { app, BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
const os = require('node:os')

app.whenReady().then(() => {
  const win = new BrowserWindow()
  win.loadURL('https://github.com')

  win.webContents.on('did-finish-load', () => {
    // 기본 프린트 옵션 사용
    const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
    win.webContents.printToPDF({}).then(data => {
      fs.writeFile(pdfPath, data, (error) => {
        if (error) throw error
        console.log(`Wrote PDF successfully to ${pdfPath}`)
      })
    }).catch(error => {
      console.log(`Failed to write PDF to ${pdfPath}: `, error)
    })
  })
})

더 많은 정보는 Page.printToPdf를 참고.

`contents.addWorkSpace(path)`

path string

지정된 경로를 DevTools 작업 공간에 추가한다. DevTools 생성 후에 사용해야 한다:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
  win.webContents.addWorkSpace(__dirname)
})

`contents.removeWorkSpace(path)`

path string

DevTools 작업 공간에서 지정된 경로를 제거한다.

`contents.setDevToolsWebContents(devToolsWebContents)`

devToolsWebContents WebContents

devToolsWebContents를 대상 WebContents로 사용하여 개발자 도구를 표시한다.

devToolsWebContents는 네비게이션을 수행한 적이 없어야 하며, 이 메서드 호출 후 다른 용도로 사용해서는 안 된다.

기본적으로 Electron은 네이티브 뷰를 가진 내부 WebContents를 생성하여 개발자 도구를 관리한다. 이 경우 개발자가 제어할 수 있는 부분이 매우 제한적이다. setDevToolsWebContents 메서드를 사용하면 BrowserWindow, BrowserView, <webview> 태그 등 어떤 WebContents든 개발자 도구를 표시할 수 있다.

개발자 도구를 닫아도 devToolsWebContents가 파괴되지 않는다. devToolsWebContents를 파괴하는 것은 호출자의 책임이다.

<webview> 태그에 개발자 도구를 표시하는 예제:

<html>
<head>
  <style type="text/css">
    * { margin: 0; }
    #browser { height: 70%; }
    #devtools { height: 30%; }
  </style>
</head>
<body>
  <webview id="browser" src="https://github.com"></webview>
  <webview id="devtools" src="about:blank"></webview>
  <script>
    const { ipcRenderer } = require('electron')
    const emittedOnce = (element, eventName) => new Promise(resolve => {
      element.addEventListener(eventName, event => resolve(event), { once: true })
    })
    const browserView = document.getElementById('browser')
    const devtoolsView = document.getElementById('devtools')
    const browserReady = emittedOnce(browserView, 'dom-ready')
    const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
    Promise.all([browserReady, devtoolsReady]).then(() => {
      const targetId = browserView.getWebContentsId()
      const devtoolsId = devtoolsView.getWebContentsId()
      ipcRenderer.send('open-devtools', targetId, devtoolsId)
    })
  </script>
</body>
</html>

// 메인 프로세스
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
  const target = webContents.fromId(targetContentsId)
  const devtools = webContents.fromId(devtoolsContentsId)
  target.setDevToolsWebContents(devtools)
  target.openDevTools()
})

BrowserWindow에 개발자 도구를 표시하는 예제:

main.js
const { app, BrowserWindow } = require('electron')

let win = null
let devtools = null

app.whenReady().then(() => {
  win = new BrowserWindow()
  devtools = new BrowserWindow()
  win.loadURL('https://github.com')
  win.webContents.setDevToolsWebContents(devtools.webContents)
  win.webContents.openDevTools({ mode: 'detach' })
})

`contents.openDevTools([options])`

options Object (선택 사항)
- mode string - 개발자 도구를 특정 도크 상태로 열 수 있다. 가능한 값은 left, right, bottom, undocked, detach이다. 기본값은 마지막으로 사용한 도크 상태이다. undocked 모드에서는 다시 도크로 돌아갈 수 있지만, detach 모드에서는 불가능하다.
- activate boolean (선택 사항) - 열린 개발자 도구 윈도우를 전경으로 가져올지 여부이다. 기본값은 true이다.
- title string (선택 사항) - 개발자 도구 윈도우의 제목이다. undocked 또는 detach 모드에서만 사용 가능하다.

개발자 도구를 연다.

contents가 <webview> 태그인 경우, mode는 기본적으로 detach로 설정된다. 명시적으로 빈 mode를 전달하면 마지막으로 사용한 도크 상태를 강제로 사용할 수 있다.

윈도우에서 Windows Control Overlay가 활성화된 경우, 개발자 도구는 mode: 'detach'로 열린다.

contents.closeDevTools()는 개발자 도구를 닫는다.

`contents.isDevToolsOpened()`

boolean을 반환한다. 개발자 도구가 열려 있는지 여부를 나타낸다.

`contents.isDevToolsFocused()`

boolean을 반환한다. 개발자 도구 뷰가 현재 포커스를 가지고 있는지 여부를 나타낸다.

`contents.getDevToolsTitle()`

string을 반환한다. 이 값은 DevTools 윈도우의 현재 제목을 나타낸다. DevTools가 undocked 또는 detach 모드로 열려 있을 때만 이 제목이 표시된다.

`contents.setDevToolsTitle(title)`

title string

DevTools 윈도우의 제목을 title로 변경한다. 이 기능은 DevTools가 undocked 또는 detach 모드로 열려 있을 때만 적용된다.

`contents.toggleDevTools()`

개발자 도구를 토글한다.

`contents.inspectElement(x, y)`

x Integer
y Integer

(x, y) 위치에 있는 엘리먼트를 검사하기 시작한다.

`contents.inspectSharedWorker()`

공유 워커 컨텍스트에 대한 개발자 도구를 연다.

`contents.inspectSharedWorkerById(workerId)`

workerId string

주어진 ID를 기반으로 공유 워커(shared worker)를 검사한다.

`contents.getAllSharedWorkers()`

SharedWorkerInfo[] 타입의 값을 반환한다. 이는 모든 Shared Worker에 대한 정보를 담고 있다.

`contents.inspectServiceWorker()`

서비스 워커 컨텍스트에 대한 개발자 도구를 열어준다.

`contents.send(channel, ...args)`

channel string
...args any[]

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

warning

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

더 자세한 내용은 Electron의 IPC 가이드를 참고한다.

`contents.sendToFrame(frameId, channel, ...args)`

frameId Integer | [number, number] - 메인 프레임과 다른 프로세스에 있는 프레임이라면 [processId, frameId] 쌍으로, 그렇지 않으면 프레임 ID를 지정한다.
channel string
...args any[]

channel을 통해 렌더러 프로세스의 특정 프레임으로 비동기 메시지를 보낸다. 인자는 postMessage와 동일하게 Structured Clone Algorithm로 직렬화되며, 프로토타입 체인은 포함되지 않는다. 함수, Promise, Symbol, WeakMap, WeakSet을 보내면 예외가 발생한다.

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

렌더러 프로세스는 ipcRenderer 모듈을 사용해 channel을 수신하여 메시지를 처리할 수 있다.

특정 렌더러 컨텍스트의 frameId를 얻으려면 webFrame.routingId 값을 사용한다. 예를 들어:

// 렌더러 프로세스에서
console.log('내 프레임 ID는:', require('electron').webFrame.routingId)

메인 프로세스에서는 모든 수신 IPC 메시지에서 frameId를 읽을 수도 있다.

// 메인 프로세스에서
ipcMain.on('ping', (event) => {
  console.info('메시지가 온 프레임 ID:', event.frameId)
})

`contents.postMessage(channel, message, [transfer])`

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

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

이전된 MessagePortMain 객체는 렌더러 프로세스에서 이벤트의 ports 속성에 접근하여 사용할 수 있다. 렌더러 프로세스에 도착하면 이 객체는 네이티브 DOM MessagePort 객체가 된다.

예시:

// 메인 프로세스
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.postMessage('port', { message: 'hello' }, [port1])

// 렌더러 프로세스
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

`contents.enableDeviceEmulation(parameters)`

parameters Object
- screenPosition string - 에뮬레이션할 화면 타입을 지정한다 (기본값: desktop):
  - desktop - 데스크톱 화면 타입.
  - mobile - 모바일 화면 타입.
- screenSize Size - 에뮬레이션할 화면 크기를 설정한다 (screenPosition == mobile).
- viewPosition Point - 화면 상에서 뷰의 위치를 설정한다 (screenPosition == mobile) (기본값: { x: 0, y: 0 }).
- deviceScaleFactor Integer - 장치 스케일 팩터를 설정한다 (0이면 기본 장치 스케일 팩터를 사용) (기본값: 0).
- viewSize Size - 에뮬레이션할 뷰 크기를 설정한다 (비어 있으면 오버라이드하지 않음)
- scale Float - 사용 가능한 공간 내에서 에뮬레이션된 뷰의 스케일을 설정한다 (fit to view 모드가 아님) (기본값: 1).

주어진 파라미터로 장치 에뮬레이션을 활성화한다.

`contents.disableDeviceEmulation()`

webContents.enableDeviceEmulation로 활성화된 디바이스 에뮬레이션을 비활성화한다.

`contents.sendInputEvent(inputEvent)`

inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

페이지에 입력 이벤트를 전송한다.
참고: sendInputEvent()가 동작하려면 BrowserWindow가 포커스 상태여야 한다.

`contents.beginFrameSubscription([onlyDirty ,]callback)`

onlyDirty boolean (선택 사항) - 기본값은 false.
callback Function
- image NativeImage
- dirtyRect Rectangle

프레젠테이션 이벤트와 캡처된 프레임을 구독하기 시작한다. 프레젠테이션 이벤트가 발생하면 callback(image, dirtyRect) 형태로 콜백 함수가 호출된다.

image는 캡처된 프레임을 저장하는 NativeImage의 인스턴스다.

dirtyRect는 페이지에서 다시 그려진 부분을 설명하는 x, y, width, height 속성을 가진 객체다. onlyDirty가 true로 설정되면 image는 다시 그려진 영역만 포함한다. onlyDirty의 기본값은 false다.

`contents.endFrameSubscription()`

프레임 프레젠테이션 이벤트 구독을 종료한다.

`contents.startDrag(item)`

item Object
- file string - 드래그할 파일의 경로
- files string[] (선택 사항) - 드래그할 파일들의 경로. (files는 file 필드를 덮어쓴다)
- icon NativeImage | string - 드래그 시 커서 아래에 표시될 이미지. macOS에서는 반드시 비어 있지 않아야 한다.

현재 드래그 앤 드롭 작업에서 item을 드래그 항목으로 설정한다. file은 드래그할 파일의 절대 경로이고, icon은 드래그 시 커서 아래에 표시될 이미지다.

`contents.savePage(fullPath, saveType)`

fullPath string - 파일의 절대 경로
saveType string - 저장 타입 지정
- HTMLOnly - 페이지의 HTML만 저장
- HTMLComplete - 완전한 HTML 페이지 저장
- MHTML - 완전한 HTML 페이지를 MHTML 형식으로 저장

반환값: Promise<void> - 페이지가 저장되면 resolve

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
    console.log('Page was saved successfully.')
  }).catch(err => {
    console.log(err)
  })
})

`contents.showDefinitionForSelection()` macOS

페이지에서 선택한 단어를 검색하는 팝업 사전을 표시한다.

`contents.isOffscreen()`

boolean 타입을 반환한다. 현재 _오프스크린 렌더링_이 활성화되어 있는지 여부를 나타낸다.

`contents.startPainting()`

_오프스크린 렌더링_이 활성화되어 있고 현재 렌더링 중이 아니라면, 렌더링을 시작한다.

contents.stopPainting()은 _오프스크린 렌더링_이 활성화되어 있고, 현재 렌더링 중인 경우 렌더링을 중지한다.

contents.isPainting()는 _오프스크린 렌더링_이 활성화된 경우 현재 페인팅 중인지 여부를 boolean 값으로 반환한다.

`contents.setFrameRate(fps)`

fps Integer

오프스크린 렌더링이 활성화된 경우, 프레임 속도를 지정된 값으로 설정한다. 1부터 240 사이의 값만 허용된다.

`contents.getFrameRate()`

Integer를 반환한다. _오프스크린 렌더링_이 활성화된 경우 현재 프레임 속도를 반환한다.

`contents.invalidate()`

이 메서드는 현재 웹 콘텐츠가 표시된 윈도우의 전체 리페인트를 예약한다.

_오프스크린 렌더링_이 활성화된 경우, 프레임을 무효화하고 'paint' 이벤트를 통해 새로운 프레임을 생성한다.

`contents.getWebRTCIPHandlingPolicy()`

string을 반환한다. 현재 설정된 WebRTC IP 처리 정책을 반환한다.

`contents.setWebRTCIPHandlingPolicy(policy)`

policy string - WebRTC IP 처리 정책을 지정한다.
- default - 사용자의 공개 IP와 로컬 IP를 모두 노출한다. 이는 기본 동작이다. 이 정책을 사용하면 WebRTC가 모든 인터페이스를 열거하고 공개 인터페이스를 탐색하기 위해 바인딩할 수 있다.
- default_public_interface_only - 사용자의 공개 IP는 노출하지만 로컬 IP는 노출하지 않는다. 이 정책을 사용하면 WebRTC는 http에서 사용하는 기본 경로만 사용해야 한다. 이 경우 로컬 주소는 노출되지 않는다.
- default_public_and_private_interfaces - 사용자의 공개 IP와 로컬 IP를 모두 노출한다. 이 정책을 사용하면 WebRTC는 http에서 사용하는 기본 경로만 사용해야 한다. 또한 연관된 기본 프라이빗 주소도 노출한다. 기본 경로는 다중 홈 엔드포인트에서 OS가 선택한 경로이다.
- disable_non_proxied_udp - 공개 IP와 로컬 IP를 모두 노출하지 않는다. 이 정책을 사용하면 WebRTC는 프록시 서버가 UDP를 지원하지 않는 한 피어나 서버와 통신할 때 TCP만 사용해야 한다.

WebRTC IP 처리 정책을 설정하면 WebRTC를 통해 어떤 IP가 노출되는지 제어할 수 있다. 더 자세한 내용은 BrowserLeaks를 참고한다.

`contents.getWebRTCUDPPortRange()`

Object를 반환한다:

min Integer - WebRTC가 사용해야 하는 최소 UDP 포트 번호
max Integer - WebRTC가 사용해야 하는 최대 UDP 포트 번호

기본값은 { min: 0, max: 0 }로, 이 경우 UDP 포트 범위에 제한이 적용되지 않는다.

`contents.setWebRTCUDPPortRange(udpPortRange)`

udpPortRange 객체
- min 정수 - WebRTC가 사용할 최소 UDP 포트 번호
- max 정수 - WebRTC가 사용할 최대 UDP 포트 번호

WebRTC UDP 포트 범위를 설정하면 WebRTC가 사용할 UDP 포트 범위를 제한할 수 있다. 기본적으로 포트 범위는 제한되지 않는다. 참고: 제한 없는 포트 범위로 재설정하려면 이 값을 { min: 0, max: 0 }으로 설정해야 한다.

`contents.getMediaSourceId(requestWebContents)`

requestWebContents WebContents - 미디어 소스 ID가 등록될 WebContents

string을 반환 - WebContents 스트림의 식별자. 이 식별자는 chromeMediaSource를 tab으로 설정한 navigator.mediaDevices.getUserMedia와 함께 사용할 수 있다. 이 식별자는 등록된 WebContents로 제한되며 10초 동안만 유효하다.

`contents.getOSProcessId()`

Integer를 반환한다. 이는 연결된 렌더러 프로세스의 운영체제 pid를 나타낸다.

`contents.getProcessId()`

Integer 타입의 값을 반환한다. 이 값은 연관된 렌더러의 Chromium 내부 pid를 나타낸다. 이 값은 프레임별 네비게이션 이벤트(예: did-frame-navigate)에서 전달되는 frameProcessId와 비교할 수 있다.

`contents.takeHeapSnapshot(filePath)`

filePath string - 출력 파일 경로

Returns Promise<void> - 스냅샷 생성 성공 여부를 나타냄

V8 힙 스냅샷을 생성하고 filePath에 저장한다.

`contents.getBackgroundThrottling()`

boolean 타입을 반환한다. 이 메서드는 페이지가 백그라운드 상태가 되었을 때, 해당 WebContents가 애니메이션과 타이머를 제한할지 여부를 나타낸다. 이 설정은 Page Visibility API에도 영향을 미친다.

`contents.setBackgroundThrottling(allowed)`

History

Version(s)	Changes
None	`WebContents.backgroundThrottling`를 false로 설정하면 호스트 `BrowserWindow` 내의 모든 `WebContents`에 영향을 미침

allowed boolean

페이지가 백그라운드 상태가 되었을 때 애니메이션과 타이머를 제한할지 여부를 설정한다. 이 설정은 Page Visibility API에도 영향을 미친다.

`contents.getType()`

string 타입을 반환한다. 웹 콘텐츠의 타입을 나타내며, backgroundPage, window, browserView, remote, webview, offscreen 중 하나의 값을 가진다.

`contents.setImageAnimationPolicy(policy)`

policy string - animate, animateOnce, 또는 noAnimation 중 하나로 설정 가능.

이 메서드는 현재 웹 콘텐츠의 이미지 애니메이션 정책을 설정한다. 이 정책은 새로운 이미지에만 적용되며, 이미 애니메이션이 진행 중인 기존 이미지에는 영향을 미치지 않는다. 이는 크로미움의 알려진 제한 사항이다. img.src = img.src를 사용하면 네트워크 트래픽 없이 이미지 애니메이션을 다시 계산할 수 있으며, 이 경우 애니메이션 정책이 업데이트된다.

이 기능은 크로미움의 animationPolicy 접근성 기능과 대응된다.

인스턴스 속성

`contents.ipc` 읽기 전용

이 WebContents에서 전송된 IPC 메시지에만 적용되는 IpcMain 범위를 가진다.

ipcRenderer.send, ipcRenderer.sendSync, ipcRenderer.postMessage로 전송된 IPC 메시지는 다음 순서로 전달된다:

contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
ipcMain.on(channel)

invoke로 등록된 핸들러는 다음 순서로 확인된다. 첫 번째로 정의된 핸들러가 호출되며, 나머지는 무시된다.

contents.mainFrame.handle(channel)
contents.handle(channel)
ipcMain.handle(channel)

WebContents에 등록된 핸들러나 이벤트 리스너는 자식 프레임을 포함한 모든 프레임에서 전송된 IPC 메시지를 받는다. 대부분의 경우 메인 프레임만 IPC 메시지를 보낼 수 있다. 하지만 nodeIntegrationInSubFrames 옵션이 활성화된 경우, 자식 프레임도 IPC 메시지를 보낼 수 있다. 이 경우 핸들러는 IPC 이벤트의 senderFrame 속성을 확인해 메시지가 예상된 프레임에서 왔는지 확인해야 한다. 또는 WebFrameMain.ipc 인터페이스를 사용해 적절한 프레임에 직접 핸들러를 등록할 수도 있다.

`contents.audioMuted`

이 속성은 boolean 타입으로, 현재 페이지의 음소거 상태를 결정한다.

`contents.userAgent`

이 속성은 웹 페이지의 사용자 에이전트(user agent)를 결정하는 문자열(string) 타입의 속성이다.

`contents.zoomLevel`

이 속성은 웹 콘텐츠의 확대/축소 수준을 결정하는 number 타입의 값이다.

기본 크기는 0이며, 이 값을 기준으로 증가 또는 감소할 때마다 20%씩 확대 또는 축소된다. 확대의 기본 상한은 원래 크기의 300%, 축소의 기본 하한은 원래 크기의 50%이다. 이 수준은 scale := 1.2 ^ level 공식으로 계산된다.

`contents.zoomFactor`

이 속성은 웹 콘텐츠의 확대/축소 비율을 결정하는 number 타입의 값이다.

확대/축소 비율은 퍼센트 값을 100으로 나눈 값으로, 예를 들어 300%는 3.0으로 표현된다.

`contents.frameRate`

contents.frameRate는 웹 콘텐츠의 프레임 속도를 지정된 숫자로 설정하는 정수형(Integer) 프로퍼티이다. 이 값은 1부터 240 사이의 범위에서만 유효하다.

이 기능은 _오프스크린 렌더링(offscreen rendering)_이 활성화된 경우에만 적용된다.

`contents.id` 읽기 전용

이 WebContents의 고유 ID를 나타내는 Integer 값이다. 이 ID는 전체 Electron 애플리케이션 내의 모든 WebContents 인스턴스에서 유일하다.

`contents.session` 읽기 전용

이 webContents에서 사용하는 Session을 나타낸다.

`contents.navigationHistory` Readonly

이 webContents가 사용하는 NavigationHistory 객체이다.

`contents.hostWebContents` 읽기 전용

이 WebContents를 소유할 수 있는 WebContents 인스턴스이다.

`contents.devToolsWebContents` 읽기 전용

주어진 WebContents와 연결된 DevTools WebContents를 나타내는 WebContents | null 타입의 프로퍼티이다.

참고: 사용자는 이 객체를 절대 저장해서는 안 된다. DevTools가 닫히면 이 객체가 null이 될 수 있기 때문이다.

`contents.debugger` 읽기 전용

이 webContents에 대한 Debugger 인스턴스를 나타낸다.

`contents.backgroundThrottling`

History

Version(s)	Changes
None	`WebContents.backgroundThrottling`를 false로 설정하면 호스트 `BrowserWindow` 내의 모든 `WebContents`에 영향을 미침

이 속성은 boolean 타입으로, 페이지가 백그라운드 상태가 될 때 애니메이션과 타이머를 제한할지 여부를 결정한다. 이 설정은 Page Visibility API에도 영향을 미친다.

`contents.mainFrame` Readonly

WebFrameMain 타입의 프로퍼티로, 페이지 프레임 계층 구조의 최상위 프레임을 나타낸다.

`contents.opener` 읽기 전용

이 WebContents를 연 프레임을 나타내는 WebFrameMain 프로퍼티다. open() 메서드를 사용하거나 target 속성이 있는 링크를 통해 네비게이션한 경우에 해당한다.

네비게이션 이벤트
메서드
WebContents 클래스

네비게이션 이벤트​

문서 네비게이션​

페이지 내 네비게이션​

프레임 네비게이션​

메서드​

webContents.getAllWebContents()​

webContents.getFocusedWebContents()​

webContents.fromId(id)​

webContents.fromFrame(frame)​

webContents.fromDevToolsTargetId(targetId)​

WebContents 클래스​

인스턴스 이벤트​

이벤트: 'did-finish-load'​

이벤트: 'did-fail-load'​

이벤트: 'did-fail-provisional-load'​

이벤트: 'did-frame-finish-load'​

이벤트: 'did-start-loading'​

이벤트: 'did-stop-loading'​

이벤트: 'dom-ready'​

이벤트: 'page-title-updated'​

이벤트: 'page-favicon-updated'​

이벤트: 'content-bounds-updated'​

이벤트: 'did-create-window'​

이벤트: 'will-navigate'​

이벤트: 'will-frame-navigate'​

이벤트: 'did-start-navigation'​

이벤트: 'will-redirect'​

이벤트: 'did-redirect-navigation'​

이벤트: 'did-navigate'​

이벤트: 'did-frame-navigate'​

이벤트: 'did-navigate-in-page'​

이벤트: 'will-prevent-unload'​

이벤트: 'render-process-gone'​

이벤트: 'unresponsive'​

이벤트: 'responsive'​

이벤트: 'plugin-crashed'​

이벤트: 'destroyed'​

이벤트: 'input-event'​

이벤트: 'before-input-event'​

이벤트: 'enter-html-full-screen'​

이벤트: 'leave-html-full-screen'​

이벤트: 'zoom-changed'​

이벤트: 'blur'​

이벤트: 'focus'​

이벤트: 'devtools-open-url'​

이벤트: 'devtools-search-query'​

이벤트: 'devtools-opened'​

이벤트: 'devtools-closed'​

이벤트: 'devtools-focused'​

이벤트: 'certificate-error'​

이벤트: 'select-client-certificate'​

이벤트: 'login'​

이벤트: 'found-in-page'​

이벤트: 'media-started-playing'​

이벤트: 'media-paused'​

Event: 'audio-state-changed'​

이벤트: 'did-change-theme-color'​

이벤트: 'update-target-url'​

이벤트: 'cursor-changed'​

이벤트: 'context-menu'​

이벤트: 'select-bluetooth-device'​

이벤트: 'paint'​

이벤트: 'devtools-reload-page'​

이벤트: 'will-attach-webview'​

이벤트: 'did-attach-webview'​

이벤트: 'console-message'​

이벤트: 'preload-error'​

이벤트: 'ipc-message'​

이벤트: 'ipc-message-sync'​

이벤트: 'preferred-size-changed'​

이벤트: 'frame-created'​

인스턴스 메서드​

contents.loadURL(url[, options])​

contents.loadFile(filePath[, options])​

contents.downloadURL(url[, options])​

contents.getURL()​

contents.getTitle()​

contents.isDestroyed()​

contents.close([opts])​

contents.isFocused()​

네비게이션 이벤트

문서 네비게이션

페이지 내 네비게이션

프레임 네비게이션

메서드

`webContents.getAllWebContents()`

`webContents.getFocusedWebContents()`

`webContents.fromId(id)`

`webContents.fromFrame(frame)`

`webContents.fromDevToolsTargetId(targetId)`

WebContents 클래스

인스턴스 이벤트

이벤트: 'did-finish-load'

이벤트: 'did-fail-load'

이벤트: 'did-fail-provisional-load'

이벤트: 'did-frame-finish-load'

이벤트: 'did-start-loading'

이벤트: 'did-stop-loading'

이벤트: 'dom-ready'

이벤트: 'page-title-updated'

이벤트: 'page-favicon-updated'

이벤트: 'content-bounds-updated'

이벤트: 'did-create-window'

이벤트: 'will-navigate'

이벤트: 'will-frame-navigate'

이벤트: 'did-start-navigation'

이벤트: 'will-redirect'

이벤트: 'did-redirect-navigation'

이벤트: 'did-navigate'

이벤트: 'did-frame-navigate'

이벤트: 'did-navigate-in-page'

이벤트: 'will-prevent-unload'

이벤트: 'render-process-gone'

이벤트: 'unresponsive'

이벤트: 'responsive'

이벤트: 'plugin-crashed'

이벤트: 'destroyed'

이벤트: 'input-event'

이벤트: 'before-input-event'

이벤트: 'enter-html-full-screen'

이벤트: 'leave-html-full-screen'

이벤트: 'zoom-changed'

이벤트: 'blur'

이벤트: 'focus'

이벤트: 'devtools-open-url'

이벤트: 'devtools-search-query'

이벤트: 'devtools-opened'

이벤트: 'devtools-closed'

이벤트: 'devtools-focused'

이벤트: 'certificate-error'

이벤트: 'select-client-certificate'

이벤트: 'login'

이벤트: 'found-in-page'

이벤트: 'media-started-playing'

이벤트: 'media-paused'

Event: 'audio-state-changed'

이벤트: 'did-change-theme-color'

이벤트: 'update-target-url'

이벤트: 'cursor-changed'

이벤트: 'context-menu'

이벤트: 'select-bluetooth-device'

이벤트: 'paint'

이벤트: 'devtools-reload-page'

이벤트: 'will-attach-webview'

이벤트: 'did-attach-webview'

이벤트: 'console-message'

이벤트: 'preload-error'

이벤트: 'ipc-message'

이벤트: 'ipc-message-sync'

이벤트: 'preferred-size-changed'

이벤트: 'frame-created'

인스턴스 메서드

`contents.loadURL(url[, options])`

`contents.loadFile(filePath[, options])`

`contents.downloadURL(url[, options])`

`contents.getURL()`

`contents.getTitle()`

`contents.isDestroyed()`

`contents.close([opts])`

`contents.isFocused()`