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.

Im Folgenden finden Sie weitere Unterschiede zwischen Offscreen-Dokumenten und normalen 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 es kann jeweils nur eines 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 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 Audioausgabe geschlossen wird. Bei allen anderen Gründen werden keine Laufzeitlimits festgelegt.

Beispiele

Lebenszyklus eines Dokuments verwalten, das nicht auf dem Bildschirm angezeigt wird

Das folgende Beispiel zeigt, wie sichergestellt wird, 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>