chrome.offscreen

Beschreibung

Berechtigungen

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

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

Verfügbarkeit

Konzepte und Verwendung

Service Worker haben keinen DOM-Zugriff und viele Websites haben Content Security Policies, die die Funktionalität von Inhaltsskripten einschränken. Mit der Offscreen API kann die Erweiterung DOM-APIs in einem verborgenen Dokument verwenden, ohne die Nutzerfreundlichkeit durch das Öffnen neuer Fenster oder Tabs zu beeinträchtigen. Die runtime API ist die einzige Erweiterungs-API, die von Offscreen-Dokumenten unterstützt wird.

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

Offscreen-Dokumente verhalten sich in folgenden Punkten anders als normale Seiten:

• Die URL eines Offscreen-Dokuments muss eine statische HTML-Datei sein, die mit der Erweiterung gebündelt ist.
• Dokumente, die nicht auf dem Bildschirm angezeigt werden, können nicht fokussiert werden.
• Ein Offscreen-Dokument ist eine Instanz von window, aber der Wert des Attributs opener ist immer null.
• Ein Erweiterungspaket kann zwar mehrere Offscreen-Dokumente enthalten, aber eine installierte Erweiterung kann jeweils nur eines geöffnet haben. Wenn die Erweiterung im Split-Modus mit einem aktiven Inkognitoprofil ausgeführt wird, können das normale und das Inkognitoprofil jeweils 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 bei der Dokumenterstellung festgelegt, um die Lebensdauer des Dokuments zu bestimmen. Mit dem Grund AUDIO_PLAYBACK wird festgelegt, dass das Dokument nach 30 Sekunden ohne Audio geschlossen wird. Bei allen anderen Gründen werden keine Lebenszeitlimits festgelegt.

Beispiele

Lebenszyklus eines Offscreen-Dokuments verwalten

Das folgende Beispiel zeigt, wie Sie dafür sorgen, dass ein Offscreen-Dokument vorhanden ist. Die Funktion setupOffscreenDocument() ruft runtime.getContexts() auf, um ein vorhandenes Offscreen-Dokument zu finden, 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 sicherzugehen, dass das Dokument vorhanden ist. Das wird im folgenden Beispiel veranschaulicht.

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() prüfen, ob ein Offscreen-Dokument vorhanden ist:

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>