webFrame

현재 웹 페이지의 렌더링을 커스터마이징한다.

프로세스: 렌더러

Electron 모듈의 webFrame 익스포트는 현재 프레임을 나타내는 WebFrame 클래스의 인스턴스다. 서브 프레임은 특정 프로퍼티와 메서드(예: webFrame.firstChild)를 통해 가져올 수 있다.

현재 페이지를 200%로 확대하는 예제:

const { webFrame } = require('electron')

webFrame.setZoomFactor(2)

메서드

WebFrame 클래스는 다음과 같은 인스턴스 메서드를 제공한다:

webFrame.setZoomFactor(factor)

• factor Double - 줌 비율. 기본값은 1.0이다.

지정된 비율로 줌 비율을 변경한다. 줌 비율은 퍼센트를 100으로 나눈 값이므로, 300%는 3.0이 된다.

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

webFrame.getZoomFactor()

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

webFrame.setZoomLevel(level)

• level number - 확대/축소 레벨

지정한 레벨로 확대/축소 레벨을 변경한다. 원래 크기는 0이며, 이 값을 기준으로 위아래로 한 단계씩 조절할 때마다 기본 크기 대비 20%씩 확대 또는 축소된다. 확대/축소의 기본 제한은 각각 원래 크기의 300%와 50%이다.

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

webFrame.getZoomLevel()

현재 줌 레벨을 number 타입으로 반환한다.

webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

• minimumLevel number
• maximumLevel number

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

참고: Electron에서는 기본적으로 시각적 줌이 비활성화되어 있다. 다시 활성화하려면 다음을 호출한다:

webFrame.setVisualZoomLevelLimits(1, 3)

참고: 시각적 줌은 핀치 투 줌 동작에만 적용된다. Cmd+/-/0 줌 단축키는 애플리케이션 메뉴의 'zoomIn', 'zoomOut', 'resetZoom' MenuItem 역할로 제어된다. 단축키를 비활성화하려면 메뉴를 직접 정의하고 줌 역할을 정의에서 제외한다.

webFrame.setSpellCheckProvider(language, provider)

• language string
• provider Object
  • spellCheck Function
    • words string[]
    • callback Function
      • misspeltWords string[]

입력 필드와 텍스트 영역에서 맞춤법 검사를 위한 프로바이더를 설정한다.

이 메서드를 사용하려면 윈도우를 생성할 때 내장된 맞춤법 검사기를 비활성화해야 한다.

const mainWindow = new BrowserWindow({
  webPreferences: {
    spellcheck: false
  }
})

provider는 맞춤법 검사를 위해 단어 배열을 받는 spellCheck 메서드를 가진 객체여야 한다. spellCheck 함수는 비동기적으로 실행되며, 완료되면 callback 함수를 호출하여 잘못된 단어 배열을 반환한다.

node-spellchecker를 프로바이더로 사용하는 예제:

const { webFrame } = require('electron')
const spellChecker = require('spellchecker')
webFrame.setSpellCheckProvider('en-US', {
  spellCheck (words, callback) {
    setTimeout(() => {
      const misspelled = words.filter(x => spellchecker.isMisspelled(x))
      callback(misspelled)
    }, 0)
  }
})

webFrame.insertCSS(css[, options])

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

string을 반환한다. 삽입된 CSS를 나중에 webFrame.removeInsertedCSS(key)를 통해 제거할 때 사용할 수 있는 고유 키를 반환한다.

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

webFrame.removeInsertedCSS(key)

• key string

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

webFrame.insertText(text)

• text string

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

webFrame.executeJavaScript(code[, userGesture, callback])

• code string
• userGesture boolean (선택 사항) - 기본값은 false.
• callback Function (선택 사항) - 스크립트 실행 후 호출된다. 프레임이 일시 중단된 상태(예: 모달 경고창 표시)가 아니라면, 실행은 동기적으로 이루어지며 콜백은 메서드가 반환되기 전에 호출된다. 이전 버전과의 호환성을 위해 에러 파라미터는 두 번째 위치에 있다.
  • result Any
  • error Error

Promise<any>를 반환한다. 실행된 코드의 결과와 함께 resolve되거나, 실행 중 에러가 발생하거나 rejected된 Promise가 반환되면 reject된다.

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

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

webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])

• worldId Integer - 자바스크립트를 실행할 세계의 ID. 0은 기본 메인 세계(콘텐츠가 실행되는 곳)이며, 999는 Electron의 contextIsolation 기능이 사용하는 세계이다. 1부터 536870911까지의 값을 허용한다.
• scripts WebSource[]
• userGesture boolean (선택 사항) - 기본값은 false이다.
• callback Function (선택 사항) - 스크립트 실행 후 호출된다. 프레임이 일시 중단된 경우(예: 모달 경고 표시)를 제외하고, 실행은 동기적으로 이루어지며 콜백은 메서드가 반환되기 전에 호출된다. 이전 버전과의 호환성을 위해 에러 파라미터는 두 번째 위치에 있다.
  • result Any
  • error Error

Promise<any>를 반환한다. 실행된 코드의 결과로 resolve되거나 실행이 시작되지 못한 경우 reject된다.

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

스크립트 실행이 실패하면, 반환된 Promise는 reject되지 않고 result는 undefined가 된다. 이는 Chromium이 격리된 세계의 에러를 외부 세계로 전파하지 않기 때문이다.

webFrame.setIsolatedWorldInfo(worldId, info)

• worldId Integer - 자바스크립트를 실행할 세계의 ID. 0은 기본 세계이며, 999는 Electron의 contextIsolation 기능에서 사용하는 세계이다. Chrome 확장 프로그램은 [1 << 20, 1 << 29) 범위의 ID를 예약한다. 여기에는 어떤 정수든 지정할 수 있다.
• info Object
  • securityOrigin string (선택 사항) - 고립된 세계의 보안 오리진.
  • csp string (선택 사항) - 고립된 세계의 콘텐츠 보안 정책.
  • name string (선택 사항) - 고립된 세계의 이름. 개발자 도구에서 유용하다.

고립된 세계의 보안 오리진, 콘텐츠 보안 정책, 그리고 이름을 설정한다. 참고: csp를 지정하면 securityOrigin도 반드시 지정해야 한다.

webFrame.getResourceUsage()

Object를 반환합니다:

• images MemoryUsageDetails
• scripts MemoryUsageDetails
• cssStyleSheets MemoryUsageDetails
• xslStyleSheets MemoryUsageDetails
• fonts MemoryUsageDetails
• other MemoryUsageDetails

Blink의 내부 메모리 캐시 사용 정보를 설명하는 객체를 반환합니다.

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

이 코드는 다음과 같은 결과를 생성합니다:

{
  images: {
    count: 22,
    size: 2549,
    liveSize: 2542
  },
  cssStyleSheets: { /* "images"와 동일 */ },
  xslStyleSheets: { /* "images"와 동일 */ },
  fonts: { /* "images"와 동일 */ },
  other: { /* "images"와 동일 */ }
}

webFrame.clearCache()

이 메서드는 더 이상 사용하지 않는 메모리(예: 이전 네비게이션에서 사용한 이미지)를 해제하려고 시도한다.

이 메서드를 무작정 호출하면 Electron의 성능이 저하될 수 있다. 비워진 캐시를 다시 채워야 하기 때문이다. 따라서 이 메서드는 앱에서 페이지가 실제로 메모리를 덜 사용하고 있다고 판단되는 상황(예: 매우 무거운 페이지에서 거의 비어 있는 페이지로 이동했고, 그 페이지에 머무를 예정인 경우)에서만 호출해야 한다.

webFrame.getFrameForSelector(selector)

• selector string - 프레임 엘리먼트를 선택하기 위한 CSS 선택자.

WebFrame을 반환한다. selector로 선택한 프레임 엘리먼트가 webFrame의 문서에 존재하면 해당 프레임을 반환한다. 만약 selector가 프레임을 선택하지 않거나, 프레임이 현재 렌더러 프로세스에 없는 경우 null을 반환한다.

webFrame.findFrameByName(name)

• name string

WebFrame을 반환한다. 주어진 name과 일치하는 webFrame의 자식 프레임을 찾는다. 해당 이름의 프레임이 없거나 현재 렌더러 프로세스에 없는 경우 null을 반환한다.

webFrame.findFrameByRoutingId(routingId)

• routingId Integer - 현재 렌더러 프로세스에서 유일한 프레임 ID를 나타내는 정수. 라우팅 ID는 WebFrame 인스턴스(webFrame.routingId)에서 가져올 수 있으며, 프레임별 WebContents 네비게이션 이벤트(예: did-frame-navigate)에서도 전달된다.

반환값 WebFrame - 주어진 routingId를 가진 WebFrame을 반환하며, 찾지 못한 경우 null을 반환한다.

webFrame.isWordMisspelled(word)

• word string - 맞춤법 검사를 할 단어.

boolean을 반환한다. 내장된 맞춤법 검사기에 따라 단어가 틀렸으면 true, 맞으면 false를 반환한다. 사전이 로드되지 않았다면 항상 false를 반환한다.

webFrame.getWordSuggestions(word)

• word string - 맞춤법이 틀린 단어

string[] 타입을 반환한다. 주어진 단어에 대한 추천 단어 목록을 제공한다. 단어가 올바르게 작성된 경우, 빈 배열을 반환한다.

속성

webFrame.top 읽기 전용

webFrame이 속한 프레임 계층 구조에서 최상위 프레임을 나타내는 WebFrame | null 타입의 속성이다. 최상위 프레임이 현재 렌더러 프로세스에 없을 경우, 이 속성은 null이 된다.

webFrame.opener 읽기 전용

webFrame을 연 프레임을 나타내는 WebFrame | null 타입의 속성이다. 만약 연 프레임이 없거나 연 프레임이 현재 렌더러 프로세스에 없는 경우, 이 속성은 null이 된다.

webFrame.parent 읽기 전용

webFrame의 부모 프레임을 나타내는 WebFrame | null 타입의 프로퍼티다. 만약 webFrame이 최상위 프레임이거나 부모가 현재 렌더러 프로세스에 없으면 이 프로퍼티는 null이 된다.

webFrame.firstChild 읽기 전용

webFrame의 첫 번째 자식 프레임을 나타내는 WebFrame | null 타입의 속성이다. webFrame에 자식이 없거나 첫 번째 자식이 현재 렌더러 프로세스에 없는 경우 이 속성은 null이 된다.

webFrame.nextSibling 읽기 전용

WebFrame | null 타입을 가지는 이 속성은 다음 형제 프레임을 나타낸다. webFrame이 부모 내에서 마지막 프레임이거나 다음 형제가 현재 렌더러 프로세스에 없는 경우, 이 속성은 null이 된다.

webFrame.routingId 읽기 전용

routingId는 현재 렌더러 프로세스 내에서 고유한 프레임 ID를 나타내는 정수(Integer) 값이다. 동일한 기본 프레임을 참조하는 서로 다른 WebFrame 인스턴스는 동일한 routingId를 갖는다.