chrome.offscreen

Beschrijving

Gebruik de offscreen API om offscreen-documenten te maken en te beheren.

Machtigingen

offscreen

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

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

Beschikbaarheid

Chroom 109+ MV3+

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: '...'
  });
});

Voor volledige voorbeelden, zie 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);
    });
  }
}

Soorten

CreateParameters

Eigenschappen

  • rechtvaardiging

    snaar

    Een door de ontwikkelaar geleverde tekenreeks die de noodzaak van de achtergrondcontext gedetailleerder uitlegt. De user-agent _mag_ dit gebruiken voor weergave aan de gebruiker.

  • redenen

    Reden []

    De reden(en) waarom de extensie het offscreen-document maakt.

  • URL

    snaar

    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 offscreen-document verantwoordelijk is voor het afspelen van audio.

"IFRAME_SCRIPTING"
Specificeert dat het offscreen-document een iframe moet insluiten en scripten om de inhoud van het iframe te wijzigen.

"DOM_SCRAPEN"
Specificeert dat het offscreen-document een iframe moet insluiten en de DOM ervan moet schrapen om informatie te extraheren.

"BLOBS"
Hiermee geeft u op dat het document buiten het scherm moet communiceren met Blob-objecten (inclusief URL.createObjectURL() ).

"DOM_PARSER"
Geeft aan dat het offscreen-document de DOMParser API moet gebruiken.

"USER_MEDIA"
Specificeert dat het document buiten het scherm moet communiceren met mediastreams van gebruikersmedia (bijvoorbeeld getUserMedia() ).

"DISPLAY_MEDIA"
Specificeert dat het document buiten het scherm moet communiceren met mediastreams van weergavemedia (bijvoorbeeld getDisplayMedia() ).

"WEB_RTC"
Geeft aan dat het offscreen-document WebRTC API's moet gebruiken.

"KLEMBORD"
Specificeert dat het offscreen-document moet communiceren met de Klembord-API .

"LOCAL_STORAGE"
Geeft aan dat het offscreen-document toegang nodig heeft tot localStorage .

"WERKNEMERS"
Specificeert dat het offscreen-document werknemers moet spawnen.

"BATTERIJ_STATUS"
Geeft aan dat het offscreen-document navigator.getBattery moet gebruiken.

"MATCH_MEDIA"
Geeft aan dat het offscreen-document window.matchMedia moet gebruiken.

"GEOLOCATIE"
Geeft aan dat het offscreen-document navigator.geolocation moet gebruiken.

Methoden

closeDocument()

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

Sluit het momenteel geopende offscreen-document voor de extensie.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

createDocument()

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

Creëert een nieuw offscreen document voor de extensie.

Parameters

  • parameters

    Parameters maken

    De parameters die het offscreen document beschrijven dat moet worden gemaakt.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.