Beschrijving
Gebruik de offscreen API om documenten buiten het scherm te maken en te beheren.
Rechten
offscreenAls je de Offscreen API wilt gebruiken, declareer je het recht "offscreen" in het extensiemanifest. Voorbeeld:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Beschikbaarheid
Concepten en gebruik
Service workers hebben geen DOM-toegang en veel websites hebben content security policies die de functionaliteit van content scripts beperken. Met de Offscreen API kan de extensie DOM-API's gebruiken in een verborgen document zonder de gebruikerservaring te onderbreken door nieuwe vensters of tabbladen te openen. De runtime API is de enige extensie-API die wordt ondersteund door offscreen documenten.
Pagina's die als documenten buiten het scherm worden geladen, worden anders verwerkt dan andere typen extensiepagina's.
De rechten van de extensie worden overgedragen naar documenten buiten het scherm, maar met beperkingen voor de toegang tot de extensie-API. Omdat de browser.runtime API bijvoorbeeld de enige extensie-API is die wordt ondersteund door documenten buiten het scherm, moet berichten worden afgehandeld met leden van die API.
Dit zijn andere manieren waarop documenten buiten het scherm zich anders gedragen dan normale pagina's:
- De URL van een document buiten het scherm moet een statisch HTML-bestand zijn dat bij de extensie is gebundeld.
- Je kunt niet focussen op documenten die buiten het scherm vallen.
- Een document buiten het scherm is een instantie van
window, maar de waarde van de propertyopeneris altijdnull. - Hoewel een extensiepakket meerdere documenten buiten het scherm kan bevatten, kan een geïnstalleerde extensie maar één document tegelijk open hebben. Als de extensie in de gesplitste modus wordt uitgevoerd met een actief incognitoprofiel, kunnen het normale en het incognitoprofiel elk één document buiten het scherm hebben.
Gebruik browser.offscreen.createDocument() en browser.offscreen.closeDocument() om een document buiten het scherm te maken en te sluiten. Voor createDocument() zijn de url van het document, een reden en een verantwoording vereist:
browser.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Redenen
Ga naar het gedeelte Redenen voor een lijst met geldige redenen. Redenen worden ingesteld tijdens het maken van het document om de levensduur van het document te bepalen. De AUDIO_PLAYBACK-reden zorgt ervoor dat het document na 30 seconden wordt gesloten als er geen audio wordt afgespeeld. Voor alle andere redenen zijn geen levensduurbeperkingen ingesteld.
Voorbeelden
De levenscyclus van een document op het scherm onderhouden
Het volgende voorbeeld toont hoe je zorgt dat er een document buiten het scherm bestaat. De
setupOffscreenDocument() functieaanroep runtime.getContexts() roept aan om een bestaand document buiten het scherm te vinden
of maakt het document als het nog niet bestaat.
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;
}
}
Voordat je een bericht naar een document buiten het scherm stuurt, bel je setupOffscreenDocument() om te zorgen dat het document bestaat, zoals in het volgende voorbeeld.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Ga naar de demo's offscreen-clipboard en offscreen-dom op GitHub voor complete voorbeelden.
Vóór Chrome 116: checken of er een document buiten het scherm is geopend
runtime.getContexts() is toegevoegd in Chrome 116. In eerdere versies van Chrome gebruik je clients.matchAll() om te checken of er een bestaand document buiten het scherm is:
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);
});
}
}
Typen
CreateParameters
Eigenschappen
-
rechtvaardiging
tekenreeks
Een door de ontwikkelaar verstrekte tekenreeks die de noodzaak van de achtergrondcontext gedetailleerder uitlegt. De user-agent _kan_ dit gebruiken om het aan de gebruiker te tonen.
-
redenen
Reden[]
De reden(en) waarom de extensie het document buiten het scherm maakt.
-
url
tekenreeks
De (relatieve) URL die in het document moet worden geladen.
Reason
Enum
TESTEN
Een reden die alleen voor testdoeleinden wordt gebruikt.
"AUDIO_PLAYBACK"
Geeft aan dat het document buiten het scherm verantwoordelijk is voor het afspelen van audio.
"IFRAME_SCRIPTING"
Geeft aan dat het document buiten het scherm een iframe moet insluiten en scripten om de content van het iframe aan te passen.
"DOM_SCRAPING"
Geeft aan dat het document buiten het scherm een iframe moet insluiten en het DOM moet scrapen om informatie te extraheren.
BLOBS
Geeft aan dat het document buiten het scherm moet communiceren met Blob-objecten (waaronder URL.createObjectURL()).
"DOM_PARSER"
Geeft aan dat het document buiten het scherm de DOMParser API moet gebruiken.
"USER_MEDIA"
Geeft aan dat het document buiten het scherm moet communiceren met mediastreaming van gebruikersmedia (bijvoorbeeld getUserMedia()).
"DISPLAY_MEDIA"
Geeft aan dat het document buiten het scherm moet communiceren met mediastromen van displaymedia (bijv. getDisplayMedia()).
"WEB_RTC"
Geeft aan dat het offscreen document WebRTC API's moet gebruiken.
KLEMBORD
Geeft aan dat het document buiten het scherm moet communiceren met de Clipboard API.
"LOCAL_STORAGE"
Geeft aan dat het offscreen document toegang nodig heeft tot localStorage.
WORKERS
Geeft aan dat het document buiten het scherm werknemers moet voortbrengen.
"BATTERY_STATUS"
Geeft aan dat het document op het scherm navigator.getBattery moet gebruiken.
'MATCH_MEDIA'
Geeft aan dat het document buiten het scherm window.matchMedia moet gebruiken.
"GEOLOCATION"
Geeft aan dat het document buiten het scherm navigator.geolocation moet gebruiken.
Methoden
closeDocument()
chrome.offscreen.closeDocument(): Promise<void>
Sluit het op dit moment geopende document buiten het scherm voor de extensie.
Retourzendingen
-
Promise<void>
Promise die wordt opgelost als het document buiten het scherm is gesloten.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Maakt een nieuw document buiten het scherm voor de extensie.
Parameters
-
parameters
De parameters die het document buiten het scherm beschrijven dat moet worden gemaakt.
Retourzendingen
-
Promise<void>
Promise die wordt opgelost als het document buiten het scherm is gemaakt en de eerste pagina is geladen.
hasDocument()
chrome.offscreen.hasDocument(): Promise<boolean>
Bepaalt of de extensie een actief document heeft.
Retourzendingen
-
Promise<boolean>
Promise die wordt opgelost met het resultaat van de vraag of de extensie een actief offscreen-document heeft.