chrome.offscreen

설명

offscreen API를 사용하여 오프스크린 문서를 만들고 관리합니다.

권한

offscreen

Offscreen API를 사용하려면 확장 프로그램 매니페스트에서 "offscreen" 권한을 선언합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "offscreen"
  ],
  ...
}

가용성

Chrome 109 이상 MV3 이상

개념 및 사용법

서비스 워커에는 DOM 액세스 권한이 없으며, 많은 웹사이트에는 콘텐츠 스크립트의 기능을 제한할 수 있습니다. Offscreen API를 사용하면 확장 프로그램에서 DOM을 사용할 수 있습니다. 새 창을 열거나 새 창을 열어 사용자 환경을 방해하지 않으면서 숨겨진 문서에 API를 넣을 수 있습니다. 탭 runtime API는 유일한 확장 프로그램 API입니다. 오프스크린 문서에서 지원됩니다

오프스크린 문서로 로드된 페이지는 다른 유형의 확장 프로그램 페이지와 다르게 처리됩니다. 확장 프로그램의 권한이 화면 밖 문서로 이전되지만 확장 프로그램 API에는 제한이 있습니다. 액세스할 수 있습니다 예를 들어 chrome.runtime API가 유일한 오프스크린 문서에서 지원하는 확장 프로그램 API. 메시지를 처리해야 함 이 API의 멤버를 사용합니다

다음은 화면 밖 문서가 일반 페이지와 다르게 작동하는 그 밖의 방법입니다.

  • 화면 밖 문서의 URL은 확장 프로그램과 함께 번들로 제공되는 정적 HTML 파일이어야 합니다.
  • 화면 밖 문서에는 포커스를 설정할 수 없습니다.
  • 오프스크린 문서는 window의 인스턴스이지만 opener 속성의 값은 항상 null입니다.
  • 확장 프로그램 패키지에는 오프스크린 문서가 여러 개 포함될 수 있지만 설치된 확장 프로그램은 한 번에 하나씩 열 수 있습니다 확장 프로그램이 실행 중인 경우 분할 모드에서 활성 시크릿 프로필이 있는 경우 일반 및 시크릿 프로필이 각각 오프스크린 문서가 하나 있습니다

chrome.offscreen.createDocument() 및 chrome.offscreen.closeDocument(): 화면 밖 만들기 및 닫기 문서를 참조하세요. createDocument()에는 문서의 url, 이유, 근거가 필요합니다.

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

이유

타당한 이유 목록은 이유 섹션을 참고하세요. 이유는 문서 수명을 결정할 수 있습니다. AUDIO_PLAYBACK 이유는 다음을 설정합니다. 30초 후에 닫히도록 설정합니다. 다른 모든 이유로는 전체 기간 한도를 설정하지 않습니다.

예

오프스크린 문서의 수명 주기 유지

다음 예는 오프스크린 문서가 있는지 확인하는 방법을 보여줍니다. 이 setupOffscreenDocument() 함수는 runtime.getContexts()를 호출하여 기존 오프스크린 문서를 만들거나 아직 존재하지 않는 경우 문서를 만듭니다.

let creating; // A global promise to avoid concurrency issues
async function setupOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one
  // of them is the offscreen document with the given path
  const offscreenUrl = chrome.runtime.getURL(path);
  const existingContexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = chrome.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

화면 밖 문서로 메시지를 보내기 전에 setupOffscreenDocument()를 호출하여 문서가 존재하는지 확인하세요.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

전체 예는 오프스크린 클립보드 및 GitHub의 offscreen-dom 데모를 참조하세요.

Chrome 116 이전: 오프스크린 문서가 열려 있는지 확인하기

runtime.getContexts()가 Chrome 116에 추가되었습니다. 이전 버전의 Chrome, clients.matchAll() 사용 기존 오프스크린 문서를 확인하려면 다음 안내를 따르세요.

async function hasOffscreenDocument() {
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
    return Boolean(contexts.length);
  } else {
    const matchedClients = await clients.matchAll();
    return await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

유형

CreateParameters

속성

  • justification

    문자열

    개발자가 제공하는 문자열로, 백그라운드 컨텍스트의 필요성을 자세히 설명합니다. 사용자 에이전트는 이를 사용자에게 표시할 _수_ 있습니다_.

  • 이유

    이유[]

    확장 프로그램에서 오프스크린 문서를 만드는 이유입니다.

  • URL

    문자열

    문서에서 로드할 (상대) URL입니다.

Reason

열거형

"TESTING"
테스트 목적으로만 사용되는 이유입니다.

"AUDIO_PLAYBACK"
화면 밖 문서가 오디오 재생을 담당함을 지정합니다.

"IFRAME_ScriptING"
iframe 콘텐츠를 수정하기 위해 오프스크린 문서에서 iframe을 삽입하고 스크립트를 작성해야 함을 지정합니다.

"DOM_SCRAPING"
화면 밖 문서에 iframe을 삽입하고 DOM을 스크래핑하여 정보를 추출해야 한다고 지정합니다.

'BLOBS'
오프스크린 문서가 Blob 객체 (URL.createObjectURL() 포함)와 상호작용해야 함을 지정합니다.

"DOM_PARSER"
오프스크린 문서에서 DOMParser API를 사용해야 함을 지정합니다.

"USER_MEDIA"
오프스크린 문서가 사용자 미디어 (예: getUserMedia())의 미디어 스트림과 상호작용해야 함을 지정합니다.

"DISPLAY_MEDIA"
오프스크린 문서가 디스플레이 미디어 (예: getDisplayMedia())의 미디어 스트림과 상호작용해야 함을 지정합니다.

"WEB_RTC"
오프스크린 문서에서 WebRTC API를 사용해야 함을 지정합니다.

"CLIPBOARD"
오프스크린 문서가 Clipboard API와 상호작용해야 함을 지정합니다.

"LOCAL_STORAGE"
화면 밖 문서에서 localStorage에 액세스해야 함을 지정합니다.

"WORKERS"
오프스크린 문서에서 작업자를 생성해야 한다고 지정합니다.

"BATTERY_STATUS"
오프스크린 문서에서 navigator.getBattery를 사용해야 한다고 지정합니다.

"MATCH_MEDIA"
오프스크린 문서에서 window.matchMedia를 사용해야 한다고 지정합니다.

"GEOLOCATION"
오프스크린 문서에서 navigator.geolocation을 사용해야 함을 지정합니다.

메서드

closeDocument()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.offscreen.closeDocument(
  callback?: function,
)

현재 열려 있는 확장 프로그램 오프스크린 문서를 닫습니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

createDocument()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

확장 프로그램의 새 오프스크린 문서를 만듭니다.

매개변수

  • 매개변수

    CreateParameters

    만들 오프스크린 문서를 설명하는 매개변수입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.