Beschreibung
Verwenden Sie die offscreen API, um Offscreen-Dokumente zu erstellen und zu verwalten.
Berechtigungen
offscreenWenn Sie die Offscreen API verwenden möchten, deklarieren Sie die Berechtigung "offscreen" 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 Policies, die die Funktionalität von Inhaltsskripts einschränken. Mit der Offscreen API kann die Erweiterung DOM APIs in einem ausgeblendeten 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, der Zugriff auf die Erweiterungs-API ist jedoch eingeschränkt. Da die browser.runtime API beispielsweise die einzige Erweiterungs-API ist, die von Offscreen-Dokumenten unterstützt wird, muss das Messaging über Mitglieder dieser API erfolgen.
Im Folgenden werden weitere Unterschiede zwischen Offscreen-Dokumenten und normalen Seiten beschrieben:
- 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 des Attributsopenerist immernull. - Ein Erweiterungspaket kann zwar mehrere Offscreen-Dokumente enthalten, eine installierte Erweiterung kann jedoch jeweils nur ein Dokument geöffnet haben. Wenn die Erweiterung im geteilten Modus mit einem aktiven Inkognitoprofil ausgeführt wird, können das normale und das Inkognitoprofil jeweils ein Offscreen-Dokument haben.
Verwenden Sie browser.offscreen.createDocument() und browser.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:
browser.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. Der Grund AUDIO_PLAYBACK legt fest, 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
Das folgende Beispiel zeigt, wie Sie sicherstellen, 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 = browser.runtime.getURL(path);
const existingContexts = await browser.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
if (existingContexts.length > 0) {
return;
}
// create offscreen document
if (creating) {
await creating;
} else {
creating = browser.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 zu prüfen, ob das Dokument vorhanden ist, wie im folgenden Beispiel gezeigt.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.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 browser.runtime) {
const contexts = await browser.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(browser.runtime.id);
});
}
}
Typen
CreateParameters
Attribute
-
Begründung
String
Ein vom Entwickler bereitgestellter String, der die Notwendigkeit des Hintergrundkontexts genauer erläutert. Der User-Agent _kann_ diese Information für die Anzeige für den Nutzer verwenden.
-
Gründe
Grund[]
Die Gründe, warum die Erweiterung das Offscreen-Dokument erstellt.
-
URL
String
Die (relative) URL, die im Dokument geladen werden soll.
Reason
Enum
"TESTING"
Ein Grund, der nur zu Testzwecken verwendet wird.
"AUDIO_PLAYBACK"
Gibt an, dass das Offscreen-Dokument für die Audiowiedergabe verantwortlich ist.
"IFRAME_SCRIPTING"
Gibt an, dass das Offscreen-Dokument einen iFrame einbetten und skripten muss, um den Inhalt des iFrames zu ändern.
"DOM_SCRAPING"
Gibt an, dass das Offscreen-Dokument einen iFrame einbetten und dessen DOM auslesen muss, um Informationen zu extrahieren.
"BLOBS"
Gibt an, dass das Offscreen-Dokument mit Blob-Objekten (einschließlich URL.createObjectURL()) interagieren muss.
"DOM_PARSER"
Gibt an, dass das Offscreen-Dokument die DOMParser API verwenden muss.
"USER_MEDIA"
Gibt an, dass das Offscreen-Dokument mit Medienstreams aus Nutzermedien (z.B. getUserMedia()) interagieren muss.
"DISPLAY_MEDIA"
Gibt an, dass das Offscreen-Dokument mit Medienstreams von Anzeigemedien (z.B. getDisplayMedia()) interagieren muss.
"WEB_RTC"
Gibt an, dass das Offscreen-Dokument WebRTC APIs verwenden muss.
"CLIPBOARD"
Gibt an, dass das Offscreen-Dokument mit der Clipboard API interagieren muss.
"LOCAL_STORAGE"
Gibt an, dass das Offscreen-Dokument Zugriff auf localStorage benötigt.
"WORKERS"
Gibt an, dass das Offscreen-Dokument Worker erstellen muss.
"BATTERY_STATUS"
Gibt an, dass das Offscreen-Dokument navigator.getBattery verwenden muss.
"MATCH_MEDIA"
Gibt an, dass das Offscreen-Dokument window.matchMedia verwenden muss.
"GEOLOCATION"
Gibt an, dass das Offscreen-Dokument navigator.geolocation verwenden muss.
Methoden
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Schließt das aktuell geöffnete Offscreen-Dokument für die Erweiterung.
Ausgabe
-
Promise<void>
Promise, das aufgelöst wird, wenn das Offscreen-Dokument geschlossen wurde.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Erstellt ein neues Offscreen-Dokument für die Erweiterung.
Parameter
-
Parameter
Die Parameter, die das zu erstellende Offscreen-Dokument beschreiben.
Ausgabe
-
Promise<void>
Promise, das aufgelöst wird, wenn das Offscreen-Dokument erstellt und der erste Seitenaufbau abgeschlossen wurde.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Bestimmt, ob die Erweiterung ein aktives Dokument hat.
Ausgabe
-
Promise<boolean>
Promise, das mit dem Ergebnis aufgelöst wird, ob die Erweiterung ein aktives Offscreen-Dokument hat.