chrome.offscreen

설명

권한

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

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

지원 대상

개념 및 사용법

서비스 워커에는 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-clipboard 및 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);
    });
  }
}

chrome.offscreen.closeDocument(
  callback?: function,
)

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)