chrome.offscreen

Beschreibung

Berechtigungen

Wenn du die Offscreen API verwenden möchtest, musst du die Berechtigung "offscreen" im Erweiterungsmanifest deklarieren. Beispiel:

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

Verfügbarkeit

Konzepte und Nutzung

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

Seiten, die als nicht sichtbare Dokumente geladen werden, werden anders gehandhabt als andere Arten von Erweiterungsseiten. Die Berechtigungen der Erweiterung gelten auch für nicht sichtbare Dokumente, allerdings mit Einschränkungen für den Zugriff auf die Erweiterungs-API. Beispiel: Da die chrome.runtime API die einzige Extensions API ist, die von nicht sichtbaren Dokumenten unterstützt wird, müssen Nachrichten über Mitglieder dieser API verarbeitet werden.

Im Folgenden finden Sie weitere Möglichkeiten, auf welche Weise sich nicht sichtbare Dokumente von normalen Seiten unterscheiden:

• Die URL eines nicht sichtbaren Dokuments muss eine statische HTML-Datei mit der Erweiterung sein.
• Nicht sichtbare Dokumente können nicht fokussiert werden.
• Ein nicht sichtbares Dokument ist eine Instanz von window, aber der Wert der zugehörigen opener-Eigenschaft ist immer null.
• Obwohl ein Erweiterungspaket mehrere nicht sichtbare Dokumente enthalten kann, kann bei einer installierten Erweiterung immer nur ein Dokument geöffnet sein. Wenn die Erweiterung im Split-Modus mit einem aktiven Inkognitoprofil ausgeführt wird, können das normale und das Inkognitoprofil jeweils ein nicht sichtbares Dokument haben.

Verwenden Sie chrome.offscreen.createDocument() und chrome.offscreen.closeDocument(), um ein nicht sichtbares 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 gültiger Gründe finden Sie im Abschnitt Gründe. Die Gründe werden während der Dokumenterstellung festgelegt, um die Lebensdauer des Dokuments zu bestimmen. Der Grund AUDIO_PLAYBACK legt fest, dass das Dokument nach 30 Sekunden ohne Audiowiedergabe geschlossen wird. Bei allen anderen Gründen werden keine lebenslangen Limits festgelegt.

Beispiele

Lebenszyklus eines nicht sichtbaren Dokuments beibehalten

Das folgende Beispiel zeigt, wie Sie dafür sorgen können, dass ein nicht sichtbares Dokument vorhanden ist. Die Funktion setupOffscreenDocument() ruft runtime.getContexts() auf, um ein vorhandenes nicht sichtbares 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 nicht sichtbares Dokument senden, rufen Sie setupOffscreenDocument() auf, um zu prüfen, ob 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 findest du in den Demos zu offscreen-clipboard und offscreen-dom auf GitHub.

Vor Chrome 116: Prüfen, ob ein nicht sichtbares 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 nicht sichtbaren 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

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

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