chrome.offscreen

Beschreibung

Berechtigungen

Wenn Sie die Offscreen API verwenden möchten, deklarieren Sie die "offscreen" Berechtigung im Erweiterungsmanifest. Beispiel:

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

Verfügbarkeit

Konzepte und Verwendung

Service Worker haben keinen DOM-Zugriff und viele Websites haben Content-Security-Richtlinien, die die Funktionalität von Content-Skripts einschränken. Mit der Offscreen API kann die Erweiterung DOM-APIs in einem ausgeblendeten Dokument verwenden, ohne die Nutzererfahrung zu beeinträchtigen, indem neue Fenster oder Tabs geöffnet werden. Die runtime API ist die einzige Erweiterungs-API die von Offscreen-Dokumenten unterstützt wird.

Seiten, die als Offscreen-Dokumente geladen werden, werden anders als andere Arten von Erweiterungsseiten verarbeitet. Die Berechtigungen der Erweiterung werden auf Offscreen-Dokumente übertragen, aber der Zugriff auf die Erweiterungs-API ist eingeschränkt. Da beispielsweise die chrome.runtime API die einzige Erweiterungs-API ist, die von Offscreen-Dokumenten unterstützt wird, muss die Nachrichtenübermittlung mit Mitgliedern dieser API erfolgen.

Offscreen-Dokumente verhalten sich auch in anderer Hinsicht anders als normale Seiten:

• Die URL eines Offscreen-Dokuments muss eine statische HTML-Datei sein, die mit der Erweiterung gebündelt ist.
• Offscreen-Dokumente können nicht fokussiert werden.
• Ein Offscreen-Dokument ist eine Instanz von window, aber der Wert der zugehörigen opener-Property ist immer null.
• Ein Erweiterungspaket kann zwar mehrere Offscreen-Dokumente enthalten, aber es kann jeweils nur eines geöffnet sein. Wenn die Erweiterung im Split-Modus mit einem aktiven Inkognitoprofil ausgeführt wird, kann jedes Profil ein Offscreen-Dokument haben.

Verwenden Sie chrome.offscreen.createDocument() und chrome.offscreen.closeDocument(), um ein Offscreen -Dokument zu erstellen und zu schließen. Für createDocument() sind die url des Dokuments, ein Grund und eine Begründung erforderlich:

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

Gründe

Eine Liste der gültigen Gründe finden Sie im Abschnitt Gründe. Gründe werden beim Erstellen des Dokuments festgelegt, um die Lebensdauer des Dokuments zu bestimmen. Mit dem Grund AUDIO_PLAYBACK wird festgelegt, dass das Dokument nach 30 Sekunden ohne Audiowiedergabe geschlossen wird. Bei allen anderen Gründen werden keine Lebensdauerlimits festgelegt.

Beispiele

Lebenszyklus eines Offscreen-Dokuments verwalten

Im folgenden Beispiel wird gezeigt, wie Sie dafür sorgen, dass ein Offscreen-Dokument vorhanden ist. Die setupOffscreenDocument() Funktion ruft runtime.getContexts() auf, um ein vorhandenes Offscreen-Dokument zu suchen, oder erstellt das Dokument, falls es noch nicht vorhanden ist.

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

Bevor Sie eine Nachricht an ein Offscreen-Dokument senden, rufen Sie setupOffscreenDocument() auf, um sicherzustellen, dass das Dokument vorhanden ist, wie im folgenden Beispiel gezeigt.

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

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

Vollständige Beispiele finden Sie in den Demos offscreen-clipboard und offscreen-dom auf GitHub.

Vor Chrome 116: Prüfen, ob ein Offscreen-Dokument geöffnet ist

runtime.getContexts() wurde in Chrome 116 hinzugefügt. In früheren Versionen von Chrome können Sie mit clients.matchAll() nach einem vorhandenen Offscreen-Dokument suchen:

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>

chrome.offscreen.hasDocument(): Promise<boolean>