Opis
Interfejsu API offscreen
możesz używać do tworzenia dokumentów poza ekranem i zarządzania nimi.
Uprawnienia
offscreen
Aby 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 zastosowanie
Skrypty service worker nie mają dostępu do modelu DOM, a wiele witryn stosuje zasady bezpieczeństwa treści, które ograniczają ich funkcjonalność. 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 runtime
API 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 dotyczącymi dostępu przez interfejs API. Na przykład interfejs API chrome.runtime
jest jedynym interfejsem API rozszerzeń obsługiwanym przez dokumenty poza ekranem, dlatego przesyłanie wiadomości musi być obsługiwane przez użytkowników tego interfejsu API.
Oto inne powody, dla których 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 udało się zaznaczyć dokumentów poza ekranem.
- Dokument poza ekranem to wystąpienie elementu
window
, ale jego wartośćopener
to zawszenull
. - Pakiet rozszerzeń może zawierać wiele dokumentów poza ekranem, ale zainstalowane rozszerzenie może być otwarte tylko raz. Jeśli rozszerzenie działa w trybie podziału z aktywnym profilem incognito, oba profile mogą zawierać jeden dokument poza ekranem.
Użyj narzędzi chrome.offscreen.createDocument()
i chrome.offscreen.closeDocument()
, aby utworzyć i zamknąć dokument poza ekranem. Funkcja createDocument()
wymaga atrybutu url
dokumentu, przyczyny i uzasadnienia:
chrome.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Przyczyny
Listę uzasadnionych przyczyn znajdziesz w sekcji Przyczyny. Przyczyny są określane podczas tworzenia dokumentu
w celu określenia jego okresu ważności. Przyczyna AUDIO_PLAYBACK
powoduje zamknięcie dokumentu po 30 sekundach bez odtwarzania dźwięku. Żadne inne przyczyny nie powodują powstawania limitów czasu życia.
Przykłady
Opiekuj się cyklem życia dokumentu poza ekranem
Z przykładu poniżej dowiesz się, jak sprawdzić, czy dokument istnieje poza ekranem. Funkcja setupOffscreenDocument()
wywołuje funkcję runtime.getContexts()
, aby znaleźć istniejący dokument poza ekranem lub utworzyć taki dokument, 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 = 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;
}
}
Zanim wyślesz wiadomość do dokumentu poza ekranem, wywołaj funkcję setupOffscreenDocument()
, by sprawdzić, czy dokument istnieje, jak pokazano w tym przykładzie.
chrome.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
chrome.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Szczegółowe przykłady znajdziesz w prezentacjach offscreen-clipboard i offscreen-dom w serwisie GitHub.
Przed Chrome 116: sprawdzanie, czy dokument poza ekranem jest otwarty
Narzędzie runtime.getContexts()
zostało dodane w Chrome 116. We wcześniejszych wersjach Chrome możesz za pomocą narzędzia clients.matchAll()
sprawdzić, czy istnieje już dokument niewidoczny na ekranie:
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);
});
}
}
Typy
CreateParameters
Właściwości
-
justowanie
string,
Ciąg tekstowy podany przez dewelopera, który bardziej szczegółowo wyjaśnia potrzebę podania kontekstu tła. Klient użytkownika _may_ użyje go do wyświetlenia użytkownikowi.
-
przyczyn(y)
Powody tworzenia dokumentu poza ekranem są tworzone przez rozszerzenie.
-
URL
string,
Względny adres URL do wczytania w dokumencie.
Reason
Enum
„TESTOWANIE”
Powód używany 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 w dokumencie pozaekranowym trzeba umieścić i skrypować element iframe w celu modyfikacji zawartości elementu iframe.
"DOM_SCRAPING"
Określa, że dokument niewidoczny na ekranie musi umieścić element iframe i pobrać z niego element DOM w celu wyodrębnienia informacji.
"BLOBS"
Określa, że dokument poza ekranem musi wchodzić w interakcje z obiektami blobów (w tym URL.createObjectURL()
).
"DOM_PARSER"
Określa, że dokument poza ekranem musi korzystać z interfejsu DOMParser API.
"USER_MEDIA"
Określa, że dokument poza ekranem musi wchodzić w interakcję ze strumieniami multimediów z multimediów użytkownika (np. getUserMedia()
).
"DISPLAY_MEDIA"
Określa, że dokument poza ekranem musi wchodzić w interakcję ze strumieniami multimediów z displayowych mediów (np. getDisplayMedia()
).
"WEB_RTC"
Określa, że dokument poza ekranem musi korzystać z interfejsów WebRTC API.
"CLIPTABLE"
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 być źródłem instancji roboczych.
"BATTERY_STATUS"
Określa, że dokument poza ekranem musi używać funkcji navigator.getBattery.
"MATCH_MEDIA"
Określa, że dokument poza ekranem musi używać atrybutu window.matchMedia.
"GEOLOCATION"
Określa, że dokument niewidoczny na ekranie musi używać navigator.geolocation.
Metody
closeDocument()
chrome.offscreen.closeDocument(
callback?: function,
)
Zamyka aktualnie otwarty dokument poza ekranem dla rozszerzenia.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
Tworzy nowy dokument poza ekranem dla rozszerzenia.
Parametry
-
Parametry
Parametry opisujące dokument poza ekranem do utworzenia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.