chrome.offscreen

Beschrijving

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

Toestemmingen

offscreen

Om de Offscreen API te gebruiken, moet u de "offscreen" -toestemming in het extensiemanifest declareren. Bijvoorbeeld:

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

Beschikbaarheid

Chrome 109+ MV3+

Concepten en gebruik

Service workers hebben geen toegang tot de DOM, en veel websites hebben contentbeveiligingsbeleid dat de functionaliteit van contentscripts beperkt. De Offscreen API stelt de extensie in staat om DOM API's te 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.

Pages loaded as offscreen documents are handled differently from other types of extension pages. The extension's permissions carry over to offscreen documents, but with limits on extension API access. For example, because the chrome.runtime API is the only extensions API supported by offscreen documents, messaging must be handled using members of that API.

Hieronder volgen andere manieren waarop documenten die niet op het scherm worden weergegeven zich anders gedragen dan normale webpagina's:

  • De URL van een document dat niet op het scherm wordt weergegeven, moet een statisch HTML-bestand zijn met de juiste extensie.
  • Documenten die zich buiten het scherm bevinden, kunnen niet worden geselecteerd.
  • Een offscreen-document is een instantie van window , maar de waarde van de opener eigenschap is altijd null .
  • Hoewel een extensiepakket meerdere documenten buiten beeld kan bevatten, kan een geïnstalleerde extensie er slechts één tegelijk geopend hebben. Als de extensie in de gesplitste modus draait met een actief incognito-profiel, kunnen zowel het normale als het incognito-profiel elk één document buiten beeld 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

Voor een lijst met geldige redenen, zie het gedeelte 'Redenen' . Redenen worden ingesteld tijdens het aanmaken van een document om de levensduur ervan te bepalen. De reden AUDIO_PLAYBACK zorgt ervoor dat het document na 30 seconden zonder audio-afspelen wordt gesloten. Alle andere redenen stellen geen levensduurlimieten in.

Voorbeelden

Beheer de levenscyclus van een document dat niet op het scherm wordt weergegeven.

Het volgende voorbeeld laat zien hoe je ervoor zorgt 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 document buiten het scherm verzendt, roept u setupOffscreenDocument() aan om te controleren of het document bestaat, zoals in het volgende voorbeeld wordt getoond.

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

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

For complete examples, see the offscreen-clipboard and offscreen-dom demos on GitHub.

Vóór Chrome 116: controleer of een document dat niet op het scherm zichtbaar is, geopend is.

runtime.getContexts() is toegevoegd in Chrome 116. In eerdere versies van Chrome gebruikte je clients.matchAll() om te controleren of er een document buiten het scherm bestond:

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);
    });
  }
}

Soorten

CreateParameters

Eigenschappen

  • rechtvaardiging

    snaar

    Een door de ontwikkelaar verstrekte tekst die de noodzaak van de achtergrondcontext nader toelicht. De user agent _kan_ deze tekst aan de gebruiker tonen.

  • redenen

    Reden []

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

  • URL

    snaar

    De (relatieve) URL die in het document moet worden geladen.

Reason

Enum

"TESTEN"
Een reden die alleen voor testdoeleinden wordt gebruikt.

"AUDIO_AFSPELEN"
Geeft aan dat het document dat niet op het scherm te zien is, verantwoordelijk is voor het afspelen van audio.

"IFRAME_SCRIPTING"
Specificeert dat het document dat niet op het scherm zichtbaar is, een iframe moet insluiten en scripten om de inhoud van het iframe te kunnen wijzigen.

"DOM_SCRAPING"
Specificeert dat het document dat niet op het scherm zichtbaar is, een iframe moet insluiten en de DOM ervan moet uitlezen om informatie te extraheren.

"KLOBS"
Geeft aan dat het offscreen-document moet interageren met Blob-objecten (inclusief URL.createObjectURL() ).

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

"GEBRUIKERSMEDIA"
Geeft aan dat het document dat niet op het scherm wordt weergegeven, moet interageren met mediastromen van gebruikersmedia (bijv. getUserMedia() ).

"WEERGAVE_MEDIA"
Geeft aan dat het offscreen-document moet interageren met mediastromen van weergavemedia (bijv. getDisplayMedia() ).

"WEB_RTC"
Geeft aan dat het document dat niet op het scherm wordt weergegeven, gebruik moet maken van WebRTC API's .

"KLEMBORD"
Geeft aan dat het document dat niet op het scherm wordt weergegeven, moet communiceren met de klembord-API .

"LOKALE_OPSLAG"
Geeft aan dat het document dat niet op het scherm wordt weergegeven toegang nodig heeft tot localStorage .

"WERKNEMERS"
Geeft aan dat het document dat niet op het scherm zichtbaar is, workers moet starten.

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

"MATCH_MEDIA"
Geeft aan dat het document dat niet op het scherm zichtbaar is, gebruik moet maken van window.matchMedia .

"GEOLOCATIE"
Geeft aan dat het document dat niet op het scherm zichtbaar is, gebruik moet maken van navigator.geolocation .

Methoden

closeDocument()

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

Sluit het momenteel geopende, niet-zichtbare document voor de extensie.

Retourneert

  • Promise<void>

    Een belofte die wordt vervuld wanneer het document dat niet op het scherm zichtbaar is, is gesloten.

createDocument()

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

Hiermee wordt een nieuw, extern document voor de extensie aangemaakt.

Parameters

  • parameters

    Parameters maken

    De parameters die het offscreen-document beschrijven dat moet worden aangemaakt.

Retourneert

  • Promise<void>

    Een belofte die wordt ingelost wanneer het document buiten het scherm is aangemaakt en de eerste paginalading is voltooid.