Beschrijving
Gebruik de offscreen API om offscreen documenten te maken en te beheren.
Rechten
offscreenAls je de Offscreen API wilt gebruiken, definieer 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 een Content Security Policy die de functionaliteit van contentscripts beperkt. 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 API voor extensies die wordt ondersteund door documenten buiten het scherm.
Pagina's die worden geladen als documenten buiten het scherm, 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 de berichtuitwisseling 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 is gebundeld met de extensie.
- Offscreen-documenten kunnen niet worden gefocust.
- Een document buiten het scherm is een instantie van
window, maar de waarde van de propertyopeneris altijdnull. - Een extensiepakket kan meerdere offscreen documenten bevatten, maar een geïnstalleerde extensie kan er maar één tegelijk openen. 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. createDocument() vereist de url van het document, een reden en een verantwoording:
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 reden AUDIO_PLAYBACK zorgt ervoor dat het document na 30 seconden wordt gesloten als er geen audio wordt afgespeeld. Voor alle andere redenen worden geen levensduurlimieten ingesteld.
Voorbeelden
De levenscyclus van een document buiten het scherm onderhouden
In het volgende voorbeeld zie je hoe je ervoor zorgt dat er een document buiten het scherm bestaat. De setupOffscreenDocument() functieaanroep runtime.getContexts() zoekt naar een bestaand offscreen document, 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, roep je setupOffscreenDocument() aan om te controleren of 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 volledige voorbeelden.
Vóór Chrome 116: checken of een offscreen document 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 offscreen document 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
-
verantwoording
tekenreeks
Een door de ontwikkelaar verstrekte tekenreeks die meer uitleg geeft over de noodzaak van de achtergrondcontext. De user-agent _kan_ dit gebruiken om 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
TESTING
Een reden die alleen wordt gebruikt voor testdoeleinden.
"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 de 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 offscreen document de DOMParser API moet gebruiken.
"USER_MEDIA"
Geeft aan dat het document buiten het scherm interactie moet hebben met mediastromen van gebruikersmedia (bijv. getUserMedia()).
"DISPLAY_MEDIA"
Geeft aan dat het document buiten het scherm moet communiceren met mediastreams van weergavemedia (bijv. getDisplayMedia()).
"WEB_RTC"
Geeft aan dat het offscreen document WebRTC API's moet gebruiken.
"CLIPBOARD"
Geeft aan dat het document buiten het scherm moet communiceren met de Clipboard API.
"LOCAL_STORAGE"
Geeft aan dat het document buiten het scherm toegang nodig heeft tot localStorage.
WORKERS
Geeft aan dat het offscreen document workers moet genereren.
"BATTERY_STATUS"
Geeft aan dat het document buiten 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()
browser.offscreen.closeDocument(): Promise<void>
Sluit het momenteel geopende document buiten het scherm voor de extensie.
Retourzendingen
-
Promise<void>
Promise die wordt opgelost als het document buiten het scherm is gesloten.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Maakt een nieuw offscreen-document voor de extensie.
Parameters
-
parameters
De parameters die het offscreen document beschrijven dat moet worden gemaakt.
Retourzendingen
-
Promise<void>
Promise die wordt opgelost als het offscreen document is gemaakt en de eerste pagina is geladen.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Bepaalt of de extensie een actief document heeft.
Retourzendingen
-
Promise<boolean>
Promise die wordt opgelost met het resultaat of de extensie een actief document buiten het scherm heeft.