설명
offscreen API를 사용하여 오프스크린 문서를 만들고 관리합니다.
권한
offscreenOffscreen 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 matchedClients.some(client => { return client.url.includes(chrome.runtime.id); }); } } 유형
CreateParameters
속성
- justification
문자열
백그라운드 컨텍스트의 필요성을 자세히 설명하는 개발자 제공 문자열입니다. 사용자 에이전트는 사용자에게 표시할 때 이를 사용할 수 있습니다(_may_).
- 이유
이유[]
확장 프로그램이 오프스크린 문서를 만드는 이유입니다.
- 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'
오프스크린 문서가 클립보드 API와 상호작용해야 함을 지정합니다.
"LOCAL_STORAGE"
오프스크린 문서가 localStorage에 액세스해야 함을 지정합니다.
'WORKERS'
화면 밖 문서가 작업자를 생성해야 함을 지정합니다.
"BATTERY_STATUS"
화면이 꺼진 문서가 navigator.getBattery를 사용해야 함을 지정합니다.
'MATCH_MEDIA'
화면 밖 문서가 window.matchMedia를 사용해야 함을 지정합니다.
'GEOLOCATION'
화면 밖 문서에서 navigator.geolocation을 사용해야 함을 지정합니다.
메서드
closeDocument()
chrome.offscreen.closeDocument(): Promise<void>
현재 열려 있는 확장 프로그램의 오프스크린 문서를 닫습니다.
반환 값
-
Promise<void>
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
확장 프로그램을 위한 새 오프스크린 문서를 만듭니다.
매개변수
- 매개변수
생성할 오프스크린 문서를 설명하는 매개변수입니다.
반환 값
-
Promise<void>