설명
offscreen
API를 사용하여 오프스크린 문서를 만들고 관리합니다.
권한
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);
});
}
}
유형
CreateParameters
속성
-
justification
string
백그라운드 컨텍스트의 필요성을 자세히 설명하는 개발자가 제공하는 문자열입니다. 사용자 에이전트는 사용자에게 디스플레이에서 이를 사용할 수 _있습니다_.
-
이유
이유[]
확장 프로그램이 화면 밖 문서를 생성하는 이유입니다.
-
url
string
문서에서 로드할 (상대) 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()
chrome.offscreen.closeDocument(
callback?: function,
)
확장 프로그램에서 현재 열려 있는 오프스크린 문서를 닫습니다.
매개변수
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
확장 프로그램의 새 오프스크린 문서를 만듭니다.
매개변수
-
매개변수
생성할 오프스크린 문서를 설명하는 매개변수입니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.