Opis
Do tworzenia dokumentów poza ekranem i zarządzania nimi używaj interfejsu API offscreen.
Uprawnienia
offscreenAby używać interfejsu Offscreen API, zadeklaruj uprawnienie "offscreen" w pliku manifestu rozszerzenia. Na przykład:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Dostępność
Pojęcia i użycie
Skrypty service worker nie mają dostępu do DOM, a wiele witryn ma zasady bezpieczeństwa treści, które ograniczają funkcjonalność skryptów treści. Interfejs Offscreen API umożliwia rozszerzeniu korzystanie z interfejsów DOM API w ukrytym dokumencie bez zakłócania wrażeń użytkownika przez otwieranie nowych okien lub kart. Interfejs API runtime jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem.
Strony wczytywane jako dokumenty poza ekranem są obsługiwane inaczej niż inne typy stron rozszerzeń.
Uprawnienia rozszerzenia są przenoszone do dokumentów poza ekranem, ale z ograniczeniami dostępu do interfejsu API rozszerzenia. Na przykład interfejs API browser.runtime jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem, dlatego wiadomości muszą być obsługiwane za pomocą elementów tego interfejsu API.
Oto inne sposoby, w jakie dokumenty poza ekranem zachowują się inaczej niż zwykłe strony:
- Adres URL dokumentu poza ekranem musi być statycznym plikiem HTML dołączonym do rozszerzenia.
- Nie można ustawić fokusu na dokumentach poza ekranem.
- Dokument poza ekranem jest instancją
window, ale wartość jego właściwościopenerto zawszenull. - Pakiet rozszerzenia może zawierać wiele dokumentów poza ekranem, ale zainstalowane rozszerzenie może mieć otwarty tylko jeden z nich naraz. Jeśli rozszerzenie działa w trybie dzielonym z aktywnym profilem incognito, profile normalny i incognito mogą mieć po 1 dokumencie poza ekranem.
Użyj browser.offscreen.createDocument() i browser.offscreen.closeDocument(), aby utworzyć i zamknąć dokument poza ekranem. createDocument() wymaga podania url dokumentu, powodu i uzasadnienia:
browser.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Przyczyny
Listę prawidłowych przyczyn znajdziesz w sekcji Przyczyny. Powody są ustawiane podczas tworzenia dokumentu, aby określić jego okres ważności. Powód AUDIO_PLAYBACK powoduje, że dokument jest zamykany po 30 sekundach bez odtwarzania dźwięku. W przypadku innych powodów nie ma limitów na cały okres.
Przykłady
Zarządzanie cyklem życia dokumentu poza ekranem
Poniższy przykład pokazuje, jak sprawdzić, czy dokument poza ekranem istnieje. Funkcja setupOffscreenDocument() wywołuje runtime.getContexts(), aby znaleźć istniejący dokument poza ekranem, lub tworzy go, jeśli jeszcze nie istnieje.
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 = browser.runtime.getURL(path);
const existingContexts = await browser.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
if (existingContexts.length > 0) {
return;
}
// create offscreen document
if (creating) {
await creating;
} else {
creating = browser.offscreen.createDocument({
url: path,
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
await creating;
creating = null;
}
}
Zanim wyślesz wiadomość do dokumentu poza ekranem, wywołaj funkcję setupOffscreenDocument(), aby upewnić się, że dokument istnieje, jak pokazano w tym przykładzie.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Pełne przykłady znajdziesz w demonstracjach offscreen-clipboard i offscreen-dom na GitHubie.
Przed Chrome 116: sprawdzanie, czy dokument poza ekranem jest otwarty
runtime.getContexts() dodano w Chrome 116. W starszych wersjach Chrome użyj clients.matchAll(), aby sprawdzić, czy istnieje dokument poza ekranem:
async function hasOffscreenDocument() {
if ('getContexts' in browser.runtime) {
const contexts = await browser.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(browser.runtime.id);
});
}
}
Typy
CreateParameters
Właściwości
-
uzasadnienie
tekst
Ciąg znaków podany przez dewelopera, który szczegółowo wyjaśnia, dlaczego potrzebny jest kontekst w tle. Klient użytkownika _może_ używać tej wartości podczas wyświetlania informacji użytkownikowi.
-
przyczyn(y)
Reason[]
Powody, dla których rozszerzenie tworzy dokument poza ekranem.
-
URL
tekst
(Względny) adres URL do wczytania w dokumencie.
Reason
Typ wyliczeniowy
"TESTING"
Przyczyna używana tylko do celów testowych.
"AUDIO_PLAYBACK"
Określa, że dokument poza ekranem jest odpowiedzialny za odtwarzanie dźwięku.
"IFRAME_SCRIPTING"
Określa, że dokument poza ekranem musi umieścić element iframe i skrypt, aby zmodyfikować zawartość elementu iframe.
"DOM_SCRAPING"
Określa, że dokument poza ekranem musi umieścić element iframe i wyodrębnić informacje z jego modelu DOM.
"BLOBS"
Określa, że dokument poza ekranem musi wchodzić w interakcje z obiektami Blob (w tym URL.createObjectURL()).
"DOM_PARSER"
Określa, że dokument poza ekranem musi używać interfejsu DOMParser API.
"USER_MEDIA"
Określa, że dokument poza ekranem musi wchodzić w interakcje ze strumieniami multimediów z multimediów użytkownika (np. getUserMedia()).
"DISPLAY_MEDIA"
Określa, że dokument poza ekranem musi wchodzić w interakcje ze strumieniami multimediów z mediów wyświetlanych (np. getDisplayMedia()).
"WEB_RTC"
Określa, że dokument poza ekranem musi używać interfejsów WebRTC API.
"CLIPBOARD"
Określa, że dokument poza ekranem musi wchodzić w interakcję z interfejsem Clipboard API.
"LOCAL_STORAGE"
Określa, że dokument poza ekranem wymaga dostępu do localStorage.
"WORKERS"
Określa, że dokument poza ekranem musi utworzyć instancje skryptów typu worker.
"BATTERY_STATUS"
Określa, że dokument poza ekranem musi używać navigator.getBattery.
"MATCH_MEDIA"
Określa, że dokument poza ekranem musi używać window.matchMedia.
"GEOLOCATION"
Określa, że dokument poza ekranem musi używać navigator.geolocation.
Metody
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Zamyka aktualnie otwarty dokument poza ekranem dla rozszerzenia.
Zwroty
-
thought Promise<void>
Obietnica, która zostanie spełniona po zamknięciu dokumentu poza ekranem.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Tworzy nowy dokument poza ekranem dla rozszerzenia.
Parametry
-
parametry
Parametry opisujące dokument poza ekranem, który ma zostać utworzony.
Zwroty
-
thought Promise<void>
Obiekt Promise, który jest rozwiązywany po utworzeniu dokumentu poza ekranem i zakończeniu jego początkowego wczytywania strony.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Określa, czy rozszerzenie ma aktywny dokument.
Zwroty
-
Promise<boolean>
Obiekt Promise, który zwraca wynik wskazujący, czy rozszerzenie ma aktywny dokument poza ekranem.