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 Verwendung

Service Worker haben keinen DOM-Zugriff und auf vielen Websites gibt es Richtlinien für die Contentsicherheit, die Funktionalität von Inhaltsskripts einschränken. Mit der Offscreen API kann die Erweiterung DOM verwenden APIs in einem verborgenen Dokument einzufügen, ohne dass die Nutzererfahrung dadurch beeinträchtigt wird, z. B. durch Öffnen neuer Fenster oder Registerkarten. Die runtime API ist die einzige Erweiterungs-API nicht unterstützt werden.

Seiten, die als nicht sichtbare Dokumente geladen werden, werden anders behandelt als andere Arten von Erweiterungsseiten. Die Berechtigungen der Erweiterung gelten für nicht sichtbare Dokumente, jedoch mit Einschränkungen für die Erweiterungs-API Zugriff haben. Da die chrome.runtime API z. B. die einzige Erweiterungs-API, die von nicht sichtbaren Dokumenten unterstützt wird, muss die Kommunikation gehandhabt werden mithilfe von Mitgliedern der API.

Im Folgenden finden Sie weitere Beispiele dafür, wie sich nicht sichtbare Dokumente von normalen Seiten unterscheiden:

• Die URL eines nicht sichtbaren Dokuments muss eine statische HTML-Datei sein, die mit der Erweiterung gebündelt ist.
• Nicht sichtbare Dokumente können nicht hervorgehoben werden.
• Ein nicht sichtbares Dokument ist eine Instanz von window, aber der Wert seiner opener-Eigenschaft ist immer null.
• Obwohl ein Erweiterungspaket mehrere nicht sichtbare Dokumente enthalten kann, kann eine installierte Erweiterung immer nur jeweils einen Bereich geöffnet. Wenn die Erweiterung ausgeführt wird im geteilten Modus mit einem aktiven Inkognito-Profil haben, können das normale und das Inkognito-Profil jeweils ein nicht sichtbares Dokument.

Verwenden Sie chrome.offscreen.createDocument() und chrome.offscreen.closeDocument(), um einen nicht sichtbaren Bereich zu erstellen und zu schließen Dokument. createDocument() erfordert die url des Dokuments, einen Grund und eine Begründung:

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

Gründe

Eine Liste möglicher Gründe finden Sie im Abschnitt Gründe. Gründe werden festgelegt während Dokumenterstellung, um die Lebensdauer des Dokuments zu bestimmen. Der Grund AUDIO_PLAYBACK legt Folgendes fest: das Dokument nach 30 Sekunden ohne Ton zu schließen. Aus allen anderen Gründen werden keine Nutzungslimits festgelegt.

Beispiele

Lebenszyklus eines nicht sichtbaren Dokuments verwalten

Das folgende Beispiel zeigt, wie Sie dafür sorgen können, dass ein nicht sichtbares Dokument vorhanden ist. Die Die Funktion setupOffscreenDocument() ruft runtime.getContexts() auf, um ein nicht sichtbares Dokument erstellen oder das Dokument erstellen, 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 sicherzugehen das Dokument existiert, 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 der Offscreen-Zwischenablage und Offscreen-Demos 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, clients.matchAll() verwenden So suchen Sie nach einem nicht sichtbaren Dokument:

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,
)