Skip to main content

<webview> 태그

주의 사항​

Electron의 <webview> 태그는 Chromium의 webview를 기반으로 한다. 현재 이 기술은 구조적으로 큰 변화를 겪고 있다. 이로 인해 렌더링, 네비게이션, 이벤트 라우팅 등 <webview>의 안정성에 영향을 미치고 있다. 따라서 현재로서는 <webview> 태그를 사용하지 않는 것을 권장하며, 대안으로 iframe, WebContentsView, 또는 임베디드 콘텐츠를 아예 사용하지 않는 구조를 고려해 보는 것이 좋다.

활성화​

Electron 5 이상 버전에서는 기본적으로 webview 태그가 비활성화되어 있다. BrowserWindow를 생성할 때 webPreferences 옵션에서 webviewTag를 설정해 태그를 활성화해야 한다. 자세한 내용은 BrowserWindow 생성자 문서를 참고한다.

개요​

외부 웹 콘텐츠를 격리된 프레임과 프로세스에서 표시한다.

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

Electron 앱에서 '게스트' 콘텐츠(예: 웹 페이지)를 포함하려면 webview 태그를 사용한다. 게스트 콘텐츠는 webview 컨테이너 안에 포함된다. 앱 내에 포함된 페이지는 게스트 콘텐츠의 레이아웃과 렌더링 방식을 제어한다.

iframe과 달리, webview는 앱과 별도의 프로세스에서 실행된다. 웹 페이지와 동일한 권한을 가지지 않으며, 앱과 포함된 콘텐츠 간의 모든 상호작용은 비동기적으로 처리된다. 이는 앱을 포함된 콘텐츠로부터 안전하게 보호한다. 참고: 호스트 페이지에서 webview에 대해 호출하는 대부분의 메서드는 메인 프로세스에 대한 동기 호출이 필요하다.

예제​

앱에 웹 페이지를 포함시키려면, 앱의 임베더 페이지(게스트 콘텐츠를 표시할 앱 페이지)에 webview 태그를 추가한다. 가장 기본적인 형태로, webview 태그는 웹 페이지의 src와 webview 컨테이너의 외관을 제어하는 CSS 스타일을 포함한다:

<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>

게스트 콘텐츠를 제어하려면, webview 이벤트를 수신하고 해당 이벤트에 반응하는 JavaScript를 작성할 수 있다. 다음은 두 개의 이벤트 리스너를 포함한 예제 코드다: 하나는 웹 페이지 로딩이 시작될 때, 다른 하나는 웹 페이지 로딩이 중지될 때를 감지하며, 로딩 중에는 "loading..." 메시지를 표시한다:

<script>
  onload = () => {
    const webview = document.querySelector('webview')
    const indicator = document.querySelector('.indicator')

    const loadstart = () => {
      indicator.innerText = 'loading...'
    }

    const loadstop = () => {
      indicator.innerText = ''
    }

    webview.addEventListener('did-start-loading', loadstart)
    webview.addEventListener('did-stop-loading', loadstop)
  }
</script>

내부 구현​

webview는 내부적으로 Out-of-Process iframes (OOPIFs)를 기반으로 구현된다. webview 태그는 기본적으로 섀도우 DOM을 사용해 iframe 엘리먼트를 감싸는 커스텀 엘리먼트다.

따라서 webview의 동작은 크로스 도메인 iframe과 매우 유사하다. 예를 들면 다음과 같다:

  • webview를 클릭하면 페이지 포커스가 임베더 프레임에서 webview로 이동한다.
  • webview에 키보드, 마우스, 스크롤 이벤트 리스너를 추가할 수 없다.
  • 임베더 프레임과 webview 간의 모든 상호작용은 비동기적으로 처리된다.

CSS 스타일링 노트​

webview 태그의 스타일은 내부적으로 display:flex;를 사용한다. 이는 전통적인 레이아웃과 플렉스 박스 레이아웃을 사용할 때 자식 iframe 엘리먼트가 webview 컨테이너의 전체 높이와 너비를 채우도록 보장하기 위함이다. 기본 display:flex; CSS 속성을 덮어쓰지 않도록 주의한다. 단, 인라인 레이아웃을 위해 display:inline-flex;를 지정하는 경우는 예외이다.

태그 속성​

webview 태그는 다음과 같은 속성을 가진다:

src​

<webview src="https://www.github.com/"></webview>

src는 현재 보이는 URL을 나타내는 문자열이다. 이 속성에 값을 할당하면 최상위 네비게이션이 시작된다.

src에 현재 값과 동일한 값을 다시 할당하면 현재 페이지를 리로드한다.

src 속성은 data:text/plain,Hello, world!와 같은 데이터 URL도 받아들일 수 있다.

nodeintegration​

<webview src="https://www.google.com/" nodeintegration></webview>

boolean 타입의 속성이다. 이 속성이 존재하면 webview 내의 게스트 페이지는 Node.js 통합을 가지게 되며, require와 process 같은 Node.js API를 사용해 시스템의 저수준 리소스에 접근할 수 있다. 기본적으로 게스트 페이지에서는 Node.js 통합이 비활성화되어 있다.

nodeintegrationinsubframes​

<webview src="https://www.google.com/" nodeintegrationinsubframes></webview>

nodeintegrationinsubframes는 webview 내부의 iframe과 같은 하위 프레임에서 NodeJS 지원을 활성화하는 실험적인 옵션이다. 이 옵션을 사용하면 모든 iframe에 대해 사전 로드(preload)가 적용된다. process.isMainFrame을 사용해 현재 프레임이 메인 프레임인지 여부를 확인할 수 있다. 이 옵션은 기본적으로 게스트 페이지에서 비활성화되어 있다.

plugins 속성​

<webview src="https://www.github.com/" plugins></webview>

boolean 타입의 속성이다. 이 속성이 존재하면 webview 내부의 게스트 페이지에서 브라우저 플러그인을 사용할 수 있다. 기본적으로 플러그인은 비활성화되어 있다.

preload​

<!-- 파일에서 로드 -->
<webview src="https://www.github.com/" preload="./test.js"></webview>
<!-- 또는 asar 아카이브에서 로드 -->
<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>

preload는 게스트 페이지에서 다른 스크립트가 실행되기 전에 로드될 스크립트를 지정하는 문자열이다. 스크립트의 URL 프로토콜은 file:이어야 한다. (asar: 아카이브를 사용하는 경우에도 마찬가지다.) 이는 내부적으로 Node의 require를 통해 로드되기 때문이며, require는 asar: 아카이브를 가상 디렉토리로 취급한다.

게스트 페이지에 Node 통합이 없더라도 이 스크립트는 모든 Node API에 접근할 수 있다. 하지만 Node가 주입한 전역 객체는 스크립트 실행이 끝난 후 삭제된다.

httpreferrer​

<webview src="https://www.github.com/" httpreferrer="https://example.com/"></webview>

string 타입의 값으로, 게스트 페이지의 리퍼러(referrer) URL을 설정한다.

useragent​

<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>

useragent는 게스트 페이지가 네비게이션되기 전에 사용자 에이전트를 설정하는 문자열이다. 페이지가 로드된 후에는 setUserAgent 메서드를 사용해 사용자 에이전트를 변경할 수 있다.

disablewebsecurity​

<webview src="https://www.github.com/" disablewebsecurity></webview>

boolean 타입의 속성이다. 이 속성이 존재하면 게스트 페이지에서 웹 보안이 비활성화된다. 웹 보안은 기본적으로 활성화되어 있다.

이 값은 첫 번째 네비게이션 이전에만 수정할 수 있다.

partition​

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electronjs.org" partition="electron"></webview>

partition은 페이지가 사용할 세션을 설정하는 문자열이다. partition이 persist:로 시작하면, 해당 페이지는 동일한 partition을 가진 앱 내의 모든 페이지에서 사용할 수 있는 영구 세션을 사용한다. persist: 접두사가 없으면, 페이지는 메모리 내 세션을 사용한다. 동일한 partition을 할당하면 여러 페이지가 같은 세션을 공유할 수 있다. partition이 설정되지 않으면 앱의 기본 세션이 사용된다.

이 값은 첫 번째 네비게이션 전에만 수정할 수 있다. 활성화된 렌더러 프로세스의 세션은 변경할 수 없기 때문이다. 이후에 이 값을 수정하려고 하면 DOM 예외가 발생한다.

allowpopups​

<webview src="https://www.github.com/" allowpopups></webview>

boolean 타입의 속성이다. 이 속성이 있으면 게스트 페이지에서 새 창을 열 수 있다. 기본적으로 팝업은 비활성화되어 있다.

webpreferences​

<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>

webpreferences는 string 타입이며, 웹뷰에 설정할 웹 환경설정을 지정하는 쉼표로 구분된 문자열 목록이다. 지원되는 모든 환경설정 문자열 목록은 BrowserWindow에서 확인할 수 있다.

이 문자열은 window.open의 기능 문자열과 동일한 형식을 따른다. 이름만 지정하면 true 불리언 값으로 설정된다. = 뒤에 값을 추가하면 해당 환경설정을 특정 값으로 설정할 수 있다. yes와 1은 true로 해석되며, no와 0은 false로 해석된다.

enableblinkfeatures​

<webview src="https://www.github.com/" enableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

enableblinkfeatures는 ,로 구분된 문자열 리스트를 값으로 받는다. 이 속성은 활성화할 Blink 기능을 지정한다.
지원되는 전체 기능 리스트는 RuntimeEnabledFeatures.json5 파일에서 확인할 수 있다.

disableblinkfeatures​

<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

disableblinkfeatures는 비활성화할 Blink 기능을 지정하는 문자열 속성이다. 이 속성은 쉼표로 구분된 문자열 리스트를 값으로 받는다. 지원되는 모든 기능 문자열은 RuntimeEnabledFeatures.json5 파일에서 확인할 수 있다.

메서드​

webview 태그는 다음과 같은 메서드를 제공한다.

참고: webview 엘리먼트는 메서드를 사용하기 전에 반드시 로드되어야 한다.

예제

const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
  webview.openDevTools()
})

<webview>.loadURL(url[, options])​

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

Promise<void>를 반환 - 페이지 로드가 완료되면 프로미스가 이행된다 (did-finish-load 참조). 페이지 로드에 실패하면 프로미스가 거부된다 (did-fail-load 참조).

webview에 url을 로드한다. url은 반드시 프로토콜 접두사(예: http:// 또는 file://)를 포함해야 한다.

<webview>.downloadURL(url[, options])​

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

url에 위치한 리소스를 다운로드하지만, 페이지 이동은 발생하지 않는다.

<webview>.getURL()은 게스트 페이지의 URL을 문자열로 반환한다.

<webview>.getTitle()​

string 타입의 값을 반환한다. 이 값은 게스트 페이지의 제목을 나타낸다.

<webview>.isLoading()

boolean 타입을 반환한다. 게스트 페이지가 여전히 리소스를 로딩 중인지 여부를 나타낸다.

<webview>.isLoadingMainFrame()​

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

<webview>.isWaitingForResponse()​

boolean을 반환한다. 게스트 페이지가 페이지의 주요 리소스에 대한 첫 번째 응답을 기다리고 있는지 여부를 나타낸다.

<webview>.stop()​

보류 중인 모든 네비게이션을 중지한다.

<webview>.reload()​

게스트 페이지를 다시 로드한다.

<webview>.reloadIgnoringCache()​

게스트 페이지를 캐시를 무시하고 다시 로드한다.

<webview>.canGoBack()는 boolean 값을 반환하며, 게스트 페이지가 뒤로 갈 수 있는지 여부를 나타낸다.

<webview>.canGoForward()는 boolean 값을 반환한다. 이 값은 게스트 페이지가 앞으로 이동할 수 있는지 여부를 나타낸다.

<webview>.canGoToOffset(offset)​

  • offset Integer

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

<webview>.clearHistory()​

네비게이션 기록을 모두 지운다.

<webview>.goBack()​

게스트 페이지를 뒤로 이동시킨다.

<webview>.goForward()​

게스트 페이지를 앞으로 이동시킨다.

<webview>.goToIndex(index)​

  • index Integer

지정된 절대 인덱스로 이동한다.

<webview>.goToOffset(offset)​

  • offset Integer

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

<webview>.isCrashed()​

boolean을 반환한다. 렌더러 프로세스가 비정상 종료되었는지 여부를 나타낸다.

<webview>.setUserAgent(userAgent)​

  • userAgent string

게스트 페이지의 사용자 에이전트(user agent)를 재정의한다.

<webview>.getUserAgent()는 게스트 페이지의 사용자 에이전트를 문자열로 반환한다.

<webview>.insertCSS(css)​

  • css string

Promise<string>을 반환한다. 이 Promise는 나중에 <webview>.removeInsertedCSS(key)를 통해 CSS를 제거할 때 사용할 수 있는 고유 키로 해결된다.

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

<webview>.removeInsertedCSS(key)​

  • key string

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

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

<webview>.executeJavaScript(code[, userGesture])​

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

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

페이지에서 code를 실행한다. userGesture가 설정된 경우, 페이지에 사용자 제스처 컨텍스트를 생성한다. requestFullScreen과 같은 사용자 동작이 필요한 HTML API는 이 옵션을 통해 자동화할 수 있다.

<webview>.openDevTools()​

게스트 페이지의 DevTools 창을 연다.

<webview>.closeDevTools()는 게스트 페이지의 개발자 도구(DevTools) 윈도우를 닫는다.

<webview>.isDevToolsOpened()

boolean을 반환한다. 게스트 페이지에 DevTools 윈도우가 연결되어 있는지 여부를 나타낸다.

<webview>.isDevToolsFocused()는 게스트 페이지의 DevTools 윈도우가 현재 포커스되었는지 여부를 나타내는 불리언 값을 반환한다.

<webview>.inspectElement(x, y)​

  • x Integer
  • y Integer

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

<webview>.inspectSharedWorker()​

게스트 페이지에 있는 공유 워커(Shared Worker) 컨텍스트의 개발자 도구(DevTools)를 연다.

<webview>.inspectServiceWorker()​

게스트 페이지에 있는 서비스 워커 컨텍스트의 DevTools를 연다.

<webview>.setAudioMuted(muted)​

  • muted boolean

게스트 페이지의 음소거 상태를 설정한다.

<webview>.isAudioMuted()​

boolean을 반환한다. 게스트 페이지의 음소거 여부를 나타낸다.

<webview>.isCurrentlyAudible()​

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

<webview>.undo()​

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

<webview>.redo()​

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

<webview>.cut()

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

<webview>.copy()​

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

<webview>.centerSelection()​

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

<webview>.paste()는 페이지 내에서 편집 명령어 paste를 실행한다.

<webview>.pasteAndMatchStyle()는 페이지 내에서 pasteAndMatchStyle 편집 명령을 실행한다. 이 메서드를 사용하면 스타일을 유지하면서 내용을 붙여넣을 수 있다.

<webview>.delete()​

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

<webview>.selectAll()은 페이지 내에서 편집 명령어 selectAll을 실행한다.

<webview>.unselect()​

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

<webview>.scrollToTop()​

현재 <webview>의 맨 위로 스크롤한다.

<webview>.scrollToBottom()​

현재 <webview>의 맨 아래로 스크롤한다.

<webview>.adjustSelection(options)​

  • options Object
    • start Number (선택 사항) - 현재 선택 영역의 시작 인덱스를 이동할 크기.
    • end Number (선택 사항) - 현재 선택 영역의 끝 인덱스를 이동할 크기.

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

예제는 webContents.adjustSelection을 참조한다.

<webview>.replace(text)​

  • text string

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

<webview>.replaceMisspelling(text)​

  • text string

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

<webview>.insertText(text)​

  • text string

Promise<void>를 반환한다.

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

<webview>.findInPage(text[, options])​

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

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

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

<webview>.stopFindInPage(action)​

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

제공된 action으로 webview의 모든 findInPage 요청을 중단한다.

<webview>.print([options])​

  • 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[] (선택 사항) - 인쇄할 페이지 범위를 설정한다.
      • 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 (선택 사항) - 인쇄할 문서의 페이지 크기를 지정한다. A3, A4, A5, Legal, Letter, Tabloid 또는 height를 마이크론 단위로 포함하는 객체를 선택할 수 있다.

반환값: Promise<void>

webview의 웹 페이지를 인쇄한다. webContents.print([options])와 동일한 기능을 수행한다.

<webview>.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<Uint8Array> - 생성된 PDF 데이터로 해결됨.

webview의 웹 페이지를 PDF로 출력함. webContents.printToPDF(options)와 동일함.

<webview>.capturePage([rect])​

  • rect Rectangle (선택 사항) - 캡처할 페이지의 영역.

반환값: Promise<NativeImage> - NativeImage로 resolve된다.

rect로 지정한 영역 내의 페이지 스냅샷을 캡처한다. rect를 생략하면 현재 보이는 전체 페이지를 캡처한다.

<webview>.send(channel, ...args)​

  • channel string
  • ...args any[]

Promise<void>를 반환한다.

channel을 통해 렌더러 프로세스로 비동기 메시지를 보낸다. 추가로 임의의 인자를 전달할 수 있다. 렌더러 프로세스는 ipcRenderer 모듈을 사용해 channel 이벤트를 수신하여 메시지를 처리할 수 있다.

예제는 webContents.send를 참고한다.

<webview>.sendToFrame(frameId, channel, ...args)​

  • frameId [number, number] - [processId, frameId]
  • channel string
  • ...args any[]

Promise<void>를 반환한다.

channel을 통해 렌더러 프로세스로 비동기 메시지를 보낸다. 임의의 인자도 함께 전달할 수 있다. 렌더러 프로세스는 ipcRenderer 모듈을 사용해 channel 이벤트를 수신함으로써 이 메시지를 처리할 수 있다.

예제는 webContents.sendToFrame을 참고한다.

<webview>.sendInputEvent(event)​

Promise<void>를 반환한다.

페이지에 입력 event를 전송한다.

event 객체에 대한 자세한 설명은 webContents.sendInputEvent를 참고한다.

<webview>.setZoomFactor(factor)​

  • factor number - 확대 비율

지정된 확대 비율로 화면을 조정한다. 확대 비율은 퍼센트 값을 100으로 나눈 값이다. 예를 들어 300%는 3.0에 해당한다.

<webview>.setZoomLevel(level)​

  • level number - 줌 레벨

지정된 레벨로 줌 레벨을 변경한다. 원본 크기는 0이며, 이 값을 기준으로 위아래로 증가할 때마다 각각 기본 크기의 20%씩 확대 또는 축소된다. 기본 제한은 원본 크기의 300%와 50%이다. 이 계산은 scale := 1.2 ^ level 공식을 따른다.

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

<webview>.getZoomFactor()는 현재 줌 배율을 숫자로 반환한다.

<webview>.getZoomLevel()

현재 확대/축소 수준을 나타내는 number 타입의 값을 반환한다.

<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

  • minimumLevel number
  • maximumLevel number

Returns Promise<void>

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

<webview>.showDefinitionForSelection() macOS​

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

<webview>.getWebContentsId()​

number 타입을 반환한다. 이 webview의 WebContents ID를 가져온다.

DOM 이벤트​

webview 태그에서 사용할 수 있는 DOM 이벤트는 다음과 같다:

이벤트: 'load-commit'​

반환값:

  • url string
  • isMainFrame boolean

이 이벤트는 로드가 완료되었을 때 발생한다. 현재 문서 내의 네비게이션과 서브프레임 문서 수준의 로드를 포함하지만, 비동기 리소스 로드는 포함하지 않는다.

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

네비게이션이 완료되면 발생하는 이벤트이다. 탭의 스피너가 멈추고, onload 이벤트가 실행된다.

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

반환값:

  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean

이 이벤트는 did-finish-load와 유사하지만, 페이지 로드가 실패하거나 취소되었을 때 발생한다. 예를 들어, window.stop()이 호출된 경우에 이 이벤트가 실행된다.

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

반환값:

  • isMainFrame boolean

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

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

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

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

이 이벤트는 탭의 스피너가 회전을 멈추는 시점에 해당한다.

이벤트: 'did-attach'​

임베더 웹 콘텐츠에 부착되었을 때 발생한다.

이벤트: 'dom-ready'​

주어진 프레임 내의 문서가 로드되면 발생한다.

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

반환값:

  • title string
  • explicitSet boolean

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

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

반환값:

  • favicons string[] - URL 배열

페이지가 파비콘 URL을 받았을 때 발생하는 이벤트.

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

HTML API에 의해 페이지가 전체 화면 모드로 전환될 때 발생한다.

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

HTML API에 의해 페이지가 전체 화면 모드를 종료할 때 발생하는 이벤트이다.

이벤트: 'console-message'​

반환값:

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

게스트 윈도우에서 콘솔 메시지를 기록할 때 발생한다.

다음 예제 코드는 로그 레벨이나 기타 속성에 상관없이 모든 로그 메시지를 임베더의 콘솔로 전달한다.

const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
  console.log('Guest page logged a message:', e.message)
})

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

반환값:

  • result 객체
    • requestId 정수
    • activeMatchOrdinal 정수 - 현재 일치하는 항목의 위치
    • matches 정수 - 일치하는 항목의 총 개수
    • selectionArea Rectangle - 첫 번째 일치 영역의 좌표
    • finalUpdate boolean - 최종 업데이트 여부

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

const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
  webview.stopFindInPage('keepSelection')
})

const requestId = webview.findInPage('test')
console.log(requestId)

이벤트: 'will-navigate'​

반환값:

  • url string

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

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

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

event.preventDefault()를 호출해도 아무런 효과가 없다.

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

반환값:

  • url string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

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

이 이벤트는 <webview>.loadURL이나 <webview>.back과 같은 API를 통해 프로그래밍적으로 네비게이션이 시작될 때는 발생하지 않는다.

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

event.preventDefault()를 호출해도 아무런 효과가 없다.

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

반환값:

  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

메인 프레임을 포함한 모든 프레임이 네비게이션을 시작할 때 발생한다. 페이지 내 네비게이션의 경우 isInPlace는 true가 된다.

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

반환값:

  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

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

이벤트: 'did-navigate'​

반환값:

  • url string

네비게이션이 완료되었을 때 발생한다.

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

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

반환값:

  • 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'​

반환값:

  • isMainFrame boolean
  • url string

페이지 내부에서 네비게이션이 발생했을 때 이벤트가 발생한다.

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

이벤트: 'close'​

게스트 페이지가 스스로 닫으려고 시도할 때 발생한다.

아래 예제 코드는 게스트가 닫으려고 할 때 webview를 about:blank로 이동시킨다.

const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
  webview.src = 'about:blank'
})

이벤트: 'ipc-message'​

반환값:

  • frameId [number, number] - [processId, frameId] 쌍
  • channel string
  • args any[]

게스트 페이지가 임베더 페이지로 비동기 메시지를 보낼 때 발생한다.

sendToHost 메서드와 ipc-message 이벤트를 사용해 게스트 페이지와 임베더 페이지 간 통신이 가능하다:

// 임베더 페이지에서
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
  console.log(event.channel)
  // "pong" 출력
})
webview.send('ping')
// 게스트 페이지에서
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', () => {
  ipcRenderer.sendToHost('pong')
})

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

반환값:

렌더러 프로세스가 예기치 않게 종료될 때 발생한다. 일반적으로 프로세스가 충돌하거나 강제 종료된 경우에 이 이벤트가 발생한다.

이벤트: 'plugin-crashed'​

반환값:

  • name string
  • version string

플러그인 프로세스가 비정상 종료될 때 발생한다.

이벤트: 'destroyed'​

WebContents가 파괴될 때 발생한다.

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

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

이벤트: 'media-paused'​

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

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

반환값:

  • themeColor string

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

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

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

반환값:

  • url string

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

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

반환값:

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

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

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

반환값:

  • event Event
  • query string - 검색할 텍스트

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

Event: 'devtools-opened'​

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

이벤트: 'devtools-closed'​

DevTools가 닫힐 때 발생한다.

이벤트: 'devtools-focused'​

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

이벤트: 'context-menu'​

반환값:

  • params 객체
    • x 정수 - x 좌표.
    • y 정수 - y 좌표.
    • linkURL 문자열 - 컨텍스트 메뉴가 호출된 노드를 감싸는 링크의 URL.
    • linkText 문자열 - 링크와 관련된 텍스트. 링크 내용이 이미지인 경우 빈 문자열일 수 있음.
    • pageURL 문자열 - 컨텍스트 메뉴가 호출된 최상위 페이지의 URL.
    • frameURL 문자열 - 컨텍스트 메뉴가 호출된 서브프레임의 URL.
    • srcURL 문자열 - 컨텍스트 메뉴가 호출된 엘리먼트의 소스 URL. 소스 URL을 가진 엘리먼트는 이미지, 오디오, 비디오 등이 있음.
    • mediaType 문자열 - 컨텍스트 메뉴가 호출된 노드의 타입. none, image, audio, video, canvas, file, plugin 중 하나.
    • hasImageContents 불리언 - 컨텍스트 메뉴가 비어 있지 않은 내용을 가진 이미지에서 호출되었는지 여부.
    • isEditable 불리언 - 컨텍스트가 편집 가능한지 여부.
    • selectionText 문자열 - 컨텍스트 메뉴가 호출된 선택 영역의 텍스트.
    • titleText 문자열 - 컨텍스트 메뉴가 호출된 선택 영역의 제목 텍스트.
    • altText 문자열 - 컨텍스트 메뉴가 호출된 선택 영역의 대체 텍스트.
    • suggestedFilename 문자열 - 컨텍스트 메뉴의 '다른 이름으로 링크 저장' 옵션을 통해 파일을 저장할 때 사용할 제안된 파일명.
    • selectionRect Rectangle - 문서 공간에서 선택 영역의 좌표를 나타내는 사각형.
    • selectionStartOffset 숫자 - 선택 텍스트의 시작 위치.
    • referrerPolicy Referrer - 메뉴가 호출된 프레임의 리퍼러 정책.
    • misspelledWord 문자열 - 커서 아래의 잘못된 단어, 존재하는 경우.
    • dictionarySuggestions 문자열[] - misspelledWord를 대체하기 위해 사용자에게 보여줄 제안된 단어 배열. 오타가 있고 맞춤법 검사기가 활성화된 경우에만 사용 가능.
    • frameCharset 문자열 - 메뉴가 호출된 프레임의 문자 인코딩.
    • formControlType 문자열 - 컨텍스트 메뉴가 호출된 소스. 가능한 값은 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 불리언 - 컨텍스트가 편집 가능한 경우, 맞춤법 검사가 활성화되었는지 여부.
    • menuSourceType 문자열 - 컨텍스트 메뉴를 호출한 입력 소스. 가능한 값은 none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, adjustSelectionReset 등이 있음.
    • mediaFlags 객체 - 컨텍스트 메뉴가 호출된 미디어 엘리먼트의 플래그.
      • inError 불리언 - 미디어 엘리먼트가 충돌했는지 여부.
      • isPaused 불리언 - 미디어 엘리먼트가 일시 중지되었는지 여부.
      • isMuted 불리언 - 미디어 엘리먼트가 음소거되었는지 여부.
      • hasAudio 불리언 - 미디어 엘리먼트에 오디오가 있는지 여부.
      • isLooping 불리언 - 미디어 엘리먼트가 반복 재생 중인지 여부.
      • isControlsVisible 불리언 - 미디어 엘리먼트의 컨트롤이 보이는지 여부.
      • canToggleControls 불리언 - 미디어 엘리먼트의 컨트롤을 토글할 수 있는지 여부.
      • canPrint 불리언 - 미디어 엘리먼트를 인쇄할 수 있는지 여부.
      • canSave 불리언 - 미디어 엘리먼트를 다운로드할 수 있는지 여부.
      • canShowPictureInPicture 불리언 - 미디어 엘리먼트가 Picture-in-Picture를 보여줄 수 있는지 여부.
      • isShowingPictureInPicture 불리언 - 미디어 엘리먼트가 현재 Picture-in-Picture를 보여주고 있는지 여부.
      • canRotate 불리언 - 미디어 엘리먼트를 회전할 수 있는지 여부.
      • canLoop 불리언 - 미디어 엘리먼트를 반복할 수 있는지 여부.
    • editFlags 객체 - 렌더러가 해당 작업을 수행할 수 있다고 판단하는지 여부를 나타내는 플래그.
      • canUndo 불리언 - 렌더러가 실행 취소를 할 수 있다고 판단하는지 여부.
      • canRedo 불리언 - 렌더러가 다시 실행을 할 수 있다고 판단하는지 여부.
      • canCut 불리언 - 렌더러가 잘라내기를 할 수 있다고 판단하는지 여부.
      • canCopy 불리언 - 렌더러가 복사를 할 수 있다고 판단하는지 여부.
      • canPaste 불리언 - 렌더러가 붙여넣기를 할 수 있다고 판단하는지 여부.
      • canDelete 불리언 - 렌더러가 삭제를 할 수 있다고 판단하는지 여부.
      • canSelectAll 불리언 - 렌더러가 전체 선택을 할 수 있다고 판단하는지 여부.
      • canEditRichly 불리언 - 렌더러가 텍스트를 풍부하게 편집할 수 있다고 판단하는지 여부.

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