electron/docs-translations/ko-KR/api/web-contents.md

webContents

webContents는 EventEmitter입니다.

웹페이지의 렌더링과 관리를 책임지며 BrowserWindow의 속성입니다. 다음은 webContents 객체를 접근하는 예입니다:

const BrowserWindow = require('electron').BrowserWindow;

var win = new BrowserWindow({width: 800, height: 1500});
win.loadURL("http://github.com");

var webContents = win.webContents;

Events

webContents 객체는 다음과 같은 이벤트들을 발생시킵니다:

Event: 'did-finish-load'

네비게이션이 끝났을 때 발생하는 이벤트입니다. 즉, 탭의 스피너가 멈추고 onload 이벤트가 발생했을 때를 얘기합니다.

Event: 'did-fail-load'

Returns:

• event Event
• errorCode Integer
• errorDescription String
• validatedURL String

이 이벤트는 did-finish-load와 비슷하나, 로드가 실패했거나 취소되었을 때도 발생합니다. 예를들면 window.stop()이 실행되었을 때 발생합니다. 모든 에러 코드들의 목록과 설명은 여기서 확인 가능합니다.

Event: 'did-frame-finish-load'

Returns:

• event Event
• isMainFrame Boolean

프레임(Frame)이 네비게이션을 끝냈을 때 발생하는 이벤트입니다.

Event: 'did-start-loading'

탭의 스피너가 회전을 시작한 시점과 같습니다.

Event: 'did-stop-loading'

탭의 스피너가 회전을 멈추었을 떄의 시점과 같습니다.

Event: 'did-get-response-details'

Returns:

• event Event
• status Boolean
• newURL String
• originalURL String
• httpResponseCode Integer
• requestMethod String
• referrer String
• headers Object

요청한 리소스의 정보가 존재할 때 발생하는 이벤트입니다. status는 리소스를 다운로드하기 위한 소켓 연결을 나타냅니다.

Event: 'did-get-redirect-request'

Returns:

• event Event
• oldURL String
• newURL String
• isMainFrame Boolean
• httpResponseCode Integer
• requestMethod String
• referrer String
• headers Object

리소스를 요청할 때 리다이렉트 응답을 받았을 때 발생하는 이벤트입니다.

Event: 'dom-ready'

Returns:

• event Event

주어진 프레임의 문서가 로드되었을 때 발생하는 이벤트입니다.

Event: 'page-favicon-updated'

Returns:

• event Event
• favicons Array - Array of URLs

페이지가 favicon을 받았을 때 발생하는 이벤트입니다.

Event: 'new-window'

Returns:

• event Event
• url String
• frameName String
• disposition String - default, foreground-tab, background-tab, new-window, other중 하나일 수 있습니다.
• options Object - 새로운 BrowserWindow를 만들 때 사용되는 옵션들입니다.

페이지가 url에 대하여 새로운 윈도우를 열기위해 요청한 경우 발생하는 이벤트입니다. window.open이나 <a target='_blank'>과 같은 외부 링크 등에 의해 요청될 수 있습니다.

기본값으로 BrowserWindow는 url로 생성됩니다.

event.preventDefault()를 호출하면 새로운 창을 만드는 것을 방지할 수 있습니다.

Event: 'will-navigate'

Returns:

• event Event
• url String

사용자 또는 페이지가 새로운 네비게이션을 원할 때 발생하는 이벤트입니다. window.location 객체가 변경되거나 사용자가 페이지의 링크를 클릭했을 때 발생합니다.

이 이벤트는 webContents.loadURL과 webContents.back 같은 API를 이용하여 프로그램적으로 시작된 네비게이션에 대해서는 발생하지 않습니다.

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

Event: 'crashed'

렌더러 프로세스가 예기치 못하게 종료되었을 때 발생되는 이벤트입니다.

Event: 'plugin-crashed'

Returns:

• event Event
• name String
• version String

플러그인 프로세스가 예기치 못하게 종료되었을 때 발생되는 이벤트입니다.

Event: 'destroyed'

webContents가 소멸될 때 발생되는 이벤트입니다.

Event: 'devtools-opened'

DevTools가 열렸을 때 발생되는 이벤트입니다.

Event: 'devtools-closed'

DevTools가 닫혔을 때 발생되는 이벤트입니다.

Event: 'devtools-focused'

DevTools에 포커스가 가거나 DevTools가 열렸을 때 발생되는 이벤트입니다.

Event: 'login'

Returns:

• event Event
• request Object
  • method String
  • url URL
  • referrer URL
• authInfo Object
  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String
• callback Function

webContents가 기본 인증을 수행하길 원할 때 발생되는 이벤트입니다.

app의 login이벤트와 사용 방법은 같습니다.

Instance Methods

webContents객체는 다음과 같은 인스턴스 메소드들을 가지고 있습니다.

webContents.session

webContents에서 사용되는 session객체를 반환합니다.

session 문서에서 이 객체의 메소드들을 확인할 수 있습니다.

webContents.loadURL(url[, options])

• url URL
• options Object (optional), 속성들:
  • httpReferrer String - HTTP Referrer url.
  • userAgent String - 요청을 시작한 유저 에이전트.
  • extraHeaders String - "\n"로 구분된 Extra 헤더들.

윈도우에 url을 로드합니다. url은 http:// or file://과 같은 프로토콜 접두사를 가지고 있어야 합니다.

webContents.getURL()

현재 웹 페이지의 URL을 반환합니다.

var win = new BrowserWindow({width: 800, height: 600});
win.loadURL("http://github.com");

var currentURL = win.webContents.getURL();

webContents.getTitle()

현재 웹 페이지의 제목을 반환합니다.

webContents.isLoading()

현재 웹 페이지가 리소스를 로드중인지 여부를 반환합니다.

webContents.isWaitingForResponse()

현재 웹 페이지가 페이지의 메인 리소스로부터 첫 응답을 기다리고있는지 여부를 반환합니다.

webContents.stop()

대기중인 네비게이션들을 모두 멈춥니다.

webContents.reload()

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

webContents.reloadIgnoringCache()

현재 페이지를 캐시를 무시한채로 새로고침합니다.

webContents.canGoBack()

브라우저가 이전의 웹 페이지로 돌아갈 수 있는지 여부를 반환합니다.

webContents.canGoForward()

브라우저가 다음 웹 페이지로 이동할 수 있는지 여부를 반환합니다.

webContents.canGoToOffset(offset)

• offset Integer

웹 페이지가 offset로 이동할 수 있는지 여부를 반환합니다.

webContents.clearHistory()

네비게이션 기록을 삭제합니다.

webContents.goBack()

브라우저가 이전 웹 페이지로 이동하게 합니다.

webContents.goForward()

브라우저가 다음 웹 페이지로 이동하게 합니다.

webContents.goToIndex(index)

• index Integer

브라우저가 지정된 절대 웹 페이지 인덱스로 네비게이트하게 합니다.

webContents.goToOffset(offset)

• offset Integer

"current entry"에서 지정된 offset으로 네비게이트 합니다.

webContents.isCrashed()

렌더러 프로세스가 예기치 않게 종료되었는지 여부를 반환합니다.

webContents.setUserAgent(userAgent)

• userAgent String

현재의 웹 페이지의 유저 에이전트를 오버라이드 합니다.

webContents.getUserAgent()

현재 웹 페이지의 유저 에이전트 String을 반환합니다.

webContents.insertCSS(css)

• css String

Injects CSS into the current web page.

webContents.executeJavaScript(code[, userGesture])

• code String
• userGesture Boolean (optional)

페이지에서 코드를 실행합니다.

브라우저 윈도우에서 requestFullScreen와 같은 몇몇 HTML API들은 사용자의 행동으로만 호출될 수 있습니다. userGesture를 true로 설정하면 이런 제약을 무시할 수 있습니다.

webContents.setAudioMuted(muted)

• muted Boolean

현재 웹 페이지의 소리를 음소거합니다.

webContents.isAudioMuted()

현재 페이지가 음소거 되어있는지 여부를 반환합니다.

webContents.undo()

웹 페이지에서 undo 에디팅 커맨드를 실행합니다.

webContents.redo()

웹 페이지에서 redo 에디팅 커맨드를 실행합니다.

webContents.cut()

웹 페이지에서 cut 에디팅 커맨드를 실행합니다.

webContents.copy()

웹 페이지에서 copy 에디팅 커맨드를 실행합니다.

webContents.paste()

웹 페이지에서 paste 에디팅 커맨드를 실행합니다.

webContents.pasteAndMatchStyle()

웹 페이지에서 pasteAndMatchStyle 에디팅 커맨드를 실행합니다.

webContents.delete()

웹 페이지에서 delete 에디팅 커맨드를 실행합니다.

webContents.selectAll()

웹 페이지에서 selectAll 에디팅 커맨드를 실행합니다.

webContents.unselect()

웹 페이지에서 unselect 에디팅 커맨드를 실행합니다.

webContents.replace(text)

• text String

웹 페이지에서 replace 에디팅 커맨드를 실행합니다.

webContents.replaceMisspelling(text)

• text String

웹 페이지에서 replaceMisspelling 에디팅 커맨드를 실행합니다.

webContents.hasServiceWorker(callback)

• callback Function

ServiceWorker가 등록되어있는지 확인하고 callback에 대한 응답으로 boolean을 반환합니다.

webContents.unregisterServiceWorker(callback)

• callback Function

ServiceWorker가 존재하면 모두 등록을 해제하고 JS promise가 만족될 때 callback에 대한 응답으로 boolean을 반환하거나 JS promise가 만족되지 않을 때 false를 반환합니다.

webContents.print([options])

options Object (optional), properties:

• silent Boolean - 사용자에게 프린트 설정을 묻지 않습니다. 기본값을 false입니다.
• printBackground Boolean - 웹 페이지의 배경 색과 이미지를 출력합니다. 기본값은 false입니다.

윈도우의 웹 페이지를 프린트합니다. silent가 false로 지정되어있을 땐, Electron이 시스템의 기본 프린터와 기본 프린터 설정을 가져옵니다.

웹 페이지에서 window.print()를 호출하는 것은 webContents.print({silent: false, printBackground: false})를 호출하는 것과 같습니다.

Note: 윈도우즈에서 print API는 pdf.dll에 의존합니다. 당신의 어플리케이션이 print 기능을 필요로 하지 않는다면 바이너리 크기를 줄이기 위해 pdf.dll을 삭제하셔도 안전합니다.

webContents.printToPDF(options, callback)

options Object, properties:

• marginsType Integer - 사용할 마진의 종류를 지정합니다.
  • 0 - default
  • 1 - none
  • 2 - minimum
• pageSize String - 생성되는 PDF의 페이지 크기를 지정합니다.
  • A4
  • A3
  • Legal
  • Letter
  • Tabloid
• printBackground Boolean - CSS 배경을 프린트할지 여부를 정합니다.
• printSelectionOnly Boolean - 선택된 영역만 프린트할지 여부를 정합니다.
• landscape Boolean - landscape을 위해선 true를, portrait를 위해선 false를 사용합니다.

callback Function - function(error, data) {}

• error Error
• data Buffer - PDF 파일 내용.

Chromium의 미리보기 프린팅 커스텀 설정을 이용하여 윈도우의 웹 페이지를 PDF로 프린트합니다.

기본으로 비어있는 options은 다음과 같이 여겨지게 됩니다:

{
  marginsType: 0,
  printBackground: false,
  printSelectionOnly: false,
  landscape: false
}

const BrowserWindow = require('electron').BrowserWindow;
const fs = require('fs');

var win = new BrowserWindow({width: 800, height: 600});
win.loadURL("http://github.com");

win.webContents.on("did-finish-load", function() {
  // Use default printing options
  win.webContents.printToPDF({}, function(error, data) {
    if (error) throw error;
    fs.writeFile("/tmp/print.pdf", data, function(error) {
      if (error)
        throw error;
      console.log("Write PDF successfully.");
    })
  })
});

webContents.addWorkSpace(path)

• path String

특정 경로를 DevTools의 워크스페이스에 추가합니다.

webContents.removeWorkSpace(path)

• path String

특정 경로를 DevTools의 워크스페이스에서 제거합니다.

webContents.openDevTools([options])

• options Object (optional). Properties:
  • detach Boolean - 새 창에서 DevTools를 엽니다.

개발자 도구를 엽니다.

webContents.closeDevTools()

개발자 도구를 닫습니다.

webContents.isDevToolsOpened()

개발자 도구가 열려있는지 여부를 반환합니다.

webContents.toggleDevTools()

개발자 도구를 토글합니다.

webContents.isDevToolsFocused()

개발자 도구에 포커스가 가있는지 여부를 반화합니다.

webContents.inspectElement(x, y)

• x Integer
• y Integer

(x, y)위치의 엘레먼트를 조사합니다.

webContents.inspectServiceWorker()

서비스 워커 컨텍스트(service worker context)를 위한 개발자 도구를 엽니다.

webContents.send(channel[, arg1][, arg2][, ...])

• channel String
• arg (optional)

channel을 통하여 렌더러 프로세스에 비동기 메시지를 보냅ㄹ니다. 임의의 아규먼트를 보낼수도 있습니다. 렌더러 프로세스는 ipcRenderer 모듈을 통하여 channel를 리슨하여 메시지를 처리할 수 있습니다.

메인 프로세스에서 렌더러 프로세스로 메시지를 보내는 예시 입니다:

// In the main process.
var window = null;
app.on('ready', function() {
  window = new BrowserWindow({width: 800, height: 600});
  window.loadURL('file://' + __dirname + '/index.html');
  window.webContents.on('did-finish-load', function() {
    window.webContents.send('ping', 'whoooooooh!');
  });
});

<!-- index.html -->
<html>
<body>
  <script>
    require('electron').ipcRenderer.on('ping', function(event, message) {
      console.log(message);  // Prints "whoooooooh!"
    });
  </script>
</body>
</html>

webContents.enableDeviceEmulation(parameters)

parameters Object, properties:

• screenPosition String - 에뮬레이트 할 화면 종료를 지정합니다 (default: desktop)
  • desktop
  • mobile
• screenSize Object - 에뮬레이트 화면의 크기를 지정합니다 (screenPosition == mobile)
  • width Integer - 에뮬레이트 화면의 너비를 지정합니다
  • height Integer - 에뮬레이트 화면의 높이를 지정합니다
• viewPosition Object - 화면에서 뷰의 위치 (screenPosition == mobile) (default: {x: 0, y: 0})
  • x Integer - 좌상단 모서리로부터의 x 축의 오프셋
  • y Integer - 좌상단 모서리로부터의 y 축의 오프셋
• deviceScaleFactor Integer - 디바이스의 스케일 팩터(scale factor)를 지정합니다. (0일 경우 기본 디바이스 스케일 팩터를 기본으로 사용합니다) (default: 0)
• viewSize Object - 에뮬레이트 된 뷰의 크기를 지정합니다 (빈 값은 오버라이드 하지 않는 다는 것을 의미합니다)
  • width Integer - 에뮬레이트 된 뷰의 너비를 지정합니다
  • height Integer - 에뮬레이트 된 뷰의 높이를 지정합니다
• fitToView Boolean - 에뮬레이트의 뷰가 사용 가능한 공간에 맞추어 스케일 다운 될지 여부를 지정합니다 (기본값: false)
• offset Object - 사용 가능한 공간에서 에뮬레이트 된 뷰의 오프셋을 지정합니다 (fit to view 모드 외에서) (기본값: {x: 0, y: 0})
  • x Float - 좌상단 모서리에서 x 축의 오프셋을 지정합니다
  • y Float - 좌상단 모서리에서 y 축의 오프셋을 지정합니다
• scale Float - 사용 가능한 공간에서 에뮬레이드 된 뷰의 스케일 (fit to view 모드 외에서) (기본값: 1)

주어진 파라미터로 디바이스 에뮬레이션을 사용합니다.

webContents.disableDeviceEmulation()

webContents.enableDeviceEmulation로 사용가능해진 디바이스 에뮬레이선을 비활성화 합니다.

webContents.sendInputEvent(event)

• event Object
  • type String (required) - 이벤트의 타입. 다음 값들이 가능합니다. mouseDown, mouseUp, mouseEnter, mouseLeave, contextMenu, mouseWheel, keyDown, keyUp, char.
  • modifiers Array - 이벤트의 수정자(modifier)들에 대한 배열. 다음 값들을 포함 할 수 있습니다. shift, control, alt, meta, isKeypad, isAutoRepeat, leftButtonDown, middleButtonDown, rightButtonDown, capsLock, numLock, left, right.

input event를 페이지로 보냅니다.

키보드 이벤트들에 대해서는 event 객체는 다음 속성들을 추가적으로 가지고 있습니다:

• keyCode String (required) - 키보드 이벤트로 보낼 수 있는 단일 캐릭터. 모든 UTF-8가 사용 가능합니다.

마우스 이벤트들에 대해서는 event 객체는 다음 속성들을 추가적으로 가지고 있습니다:

• x Integer (required)
• y Integer (required)
• button String - 눌린 버튼. 다음 값들이 가능합니다. left, middle, right
• globalX Integer
• globalY Integer
• movementX Integer
• movementY Integer
• clickCount Integer

mouseWheel 이벤트에 대해서는 event 객체는 다음 속성들을 추가적으로 가지고 있습니다:

• deltaX Integer
• deltaY Integer
• wheelTicksX Integer
• wheelTicksY Integer
• accelerationRatioX Integer
• accelerationRatioY Integer
• hasPreciseScrollingDeltas Boolean
• canScroll Boolean

webContents.beginFrameSubscription(callback)

• callback Function

프레젠테이션 이벤트들과 캡쳐된 프레임들에 대한 구독을 시작하면 callback이 프레젠테이션 이벤트가 발생할 때 callback(frameBuffer)과 같은 형식으로 호출됩니다.

frameBuffer는 raw 픽셀 데이터를 포함한 Buffer입니다. 대부분의 기계에서 픽셀 데이터는 32bit BGRA 포맷으로 효율적으로 저장됩니다. 하지만 실제 재프리젠테이션은 프로세서의 endianness에 의존성을 가지고 있습니다(대부분의 현재 프로세스들은 little-endian입니다. big-endian 프로세서들를 가진 기계들에서 data는 32bit ARGB format입니다).

webContents.endFrameSubscription()

프레임 프레젠테이션 이벤트들에 대한 구독을 중지합니다.

Instance Properties

WebContents객체들은 다음 속성들을 가지고 있습니다:

webContents.devToolsWebContents

이 WebContents에 대한 DevTools의 WebContents를 가져옵니다.

Note: 사용자가 절대로 이 객체를 저장해서는 안됩니다. 그럴경우 DevTools가 닫혔을 때, null이 될 수도 있습니다.

webContents.savePage(fullPath, saveType, callback)

• fullPath String - 전체 파일 경로.
• saveType String - 저장 타입을 지정합니다.
  • HTMLOnly - 페이지의 HTML만 저장합니다.
  • HTMLComplete - 페이지의 완성된 HTML을 저장합니다.
  • MHTML - 페이지의 완성된 HTML을 MHTML로 저장합니다.
• callback Function - function(error) {}.
  • error Error

만약 페이지를 저장하는 프로세스가 성공적으로 끝났을 경우 true를 반환합니다.

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

win.webContents.on('did-finish-load', function() {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) {
    if (!error)
      console.log("Save page successfully");
  });
});