chrome.offscreen

Beschrijving

Machtigingen

Om de Offscreen API te gebruiken, declareert u de machtiging "offscreen" in het extensiemanifest . Bijvoorbeeld:

{   "name": "My extension",   ...   "permissions": [     "offscreen"   ],   ... } 

Beschikbaarheid

Begrippen en gebruik

Serviceworkers hebben geen DOM-toegang en veel websites hanteren contentbeveiligingsbeleid dat de functionaliteit van contentscripts beperkt. Met de Offscreen API kan de extensie DOM API's in een verborgen document gebruiken zonder de gebruikerservaring te verstoren door nieuwe vensters of tabbladen te openen. De runtime API is de enige extensie-API die door offscreen-documenten wordt ondersteund.

Pagina's die als offscreen-documenten worden geladen, worden anders verwerkt dan andere typen extensiepagina's. De rechten van de extensie worden overgedragen naar offscreen-documenten, maar met beperkingen op de toegang tot de extensie-API. Omdat de chrome.runtime API bijvoorbeeld de enige extensie-API is die door offscreen-documenten wordt ondersteund, moet berichten worden verwerkt met behulp van leden van die API.

Hieronder staan andere manieren waarop offscreen-documenten zich anders gedragen dan normale pagina's:

• De URL van een offscreen-document moet een statisch HTML-bestand zijn met de extensie .
• Documenten buiten het scherm kunnen niet worden scherpgesteld.
• Een offscreen-document is een instantie van window , maar de waarde van de opener -eigenschap is altijd null .
• Hoewel een extensiepakket meerdere offscreen-documenten kan bevatten, kan een geïnstalleerde extensie er slechts één tegelijk geopend hebben. Als de extensie in de split-modus draait met een actief incognitoprofiel, kunnen het normale en incognitoprofiel elk één offscreen-document bevatten.

Gebruik chrome.offscreen.createDocument() en chrome.offscreen.closeDocument() om een offscreen-document te maken en te sluiten. createDocument() vereist de url van het document, een reden en een rechtvaardiging:

chrome.offscreen.createDocument({   url: 'off_screen.html',   reasons: ['CLIPBOARD'],   justification: 'reason for needing the document', }); 

Redenen

Zie het gedeelte Redenen voor een lijst met geldige redenen. Redenen worden ingesteld tijdens het maken van een document om de levensduur van het document te bepalen. De reden AUDIO_PLAYBACK zorgt ervoor dat het document na 30 seconden zonder audio wordt gesloten. Alle andere redenen stellen geen levensduurlimieten in.

Voorbeelden

De levenscyclus van een offscreen-document behouden

Het volgende voorbeeld laat zien hoe u ervoor kunt zorgen dat een offscreen-document bestaat. De functie setupOffscreenDocument() roept runtime.getContexts() aan om een bestaand offscreen-document te vinden, of maakt het document aan 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 = 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;   } } 

Voordat u een bericht naar een offscreen-document stuurt, roept u setupOffscreenDocument() aan om te controleren of het document bestaat, zoals in het volgende voorbeeld wordt gedemonstreerd.

chrome.action.onClicked.addListener(async () => {   await setupOffscreenDocument('off_screen.html');    // Send message to offscreen document   chrome.runtime.sendMessage({     type: '...',     target: 'offscreen',     data: '...'   }); }); 

Voor complete voorbeelden, zie de offscreen-clipboard en offscreen-dom demo's op GitHub.

Vóór Chrome 116: controleren of een offscreen-document geopend is

runtime.getContexts() is toegevoegd in Chrome 116. In eerdere versies van Chrome kunt u clients.matchAll() gebruiken om te controleren op een bestaand offscreen-document:

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 matchedClients.some(client => {       return client.url.includes(chrome.runtime.id);     });   } } 

chrome.offscreen.closeDocument(): Promise<void>

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>