chrome.offscreen

Beschrijving

Machtigingen

Als u de Offscreen API wilt gebruiken, geeft u de machtiging "offscreen" op in het extensiemanifest . Bijvoorbeeld:

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

Beschikbaarheid

Concepten en gebruik

Servicemedewerkers hebben geen DOM-toegang en veel websites hebben een inhoudsbeveiligingsbeleid dat de functionaliteit van inhoudsscripts beperkt. Dankzij 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 offscreen-documenten worden geladen, worden anders behandeld dan andere typen extensiepagina's. De machtigingen van de extensie worden overgedragen naar documenten buiten het scherm, maar met beperkingen op de API-toegang van de extensie. Omdat de chrome.runtime API bijvoorbeeld de enige extensie-API is die wordt ondersteund door offscreen-documenten, moeten berichten worden afgehandeld met behulp van leden van die API.

Hier volgen enkele 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, gebundeld met de extensie.
• Documenten buiten het scherm kunnen niet worden scherpgesteld.
• Een document buiten het scherm is een exemplaar van window , maar de waarde van de opener eigenschap is altijd null .
• Hoewel een uitbreidingspakket meerdere documenten buiten het scherm kan bevatten, kan er voor een geïnstalleerde extensie slechts één tegelijk geopend zijn. Als de extensie in de gesplitste modus wordt uitgevoerd met een actief incognitoprofiel, kunnen het normale en incognitoprofiel elk één document buiten het scherm hebben.

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 de sectie Redenen voor een lijst met geldige redenen. Tijdens het maken van het document worden redenen ingesteld om de levensduur van het document te bepalen. De reden AUDIO_PLAYBACK zorgt ervoor dat het document wordt gesloten na 30 seconden zonder dat er audio wordt afgespeeld. Alle andere redenen stellen geen levenslimieten.

Voorbeelden

Behoud de levenscyclus van een document buiten het scherm

In het volgende voorbeeld ziet u hoe u ervoor kunt zorgen dat er een document buiten het scherm bestaat. De functie setupOffscreenDocument() roept runtime.getContexts() aan om een ​​bestaand offscreen-document te zoeken, 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 = 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 document buiten het scherm verzendt, roept u setupOffscreenDocument() aan om er zeker van te zijn dat het document bestaat, zoals wordt gedemonstreerd in het volgende voorbeeld.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Zie voor volledige voorbeelden de offscreen-clipboard- en offscreen-dom- demo's op GitHub.

Vóór Chrome 116: controleer of er een offscreen document geopend is

runtime.getContexts() is toegevoegd in Chrome 116. In eerdere versies van Chrome gebruikt u clients.matchAll() 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

chrome.offscreen.closeDocument(
  callback?: function,
)

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)