Descrizione
Utilizza l'API offscreen per creare e gestire documenti fuori schermo.
Autorizzazioni
offscreenPer utilizzare l'API Offscreen, dichiara l'autorizzazione "offscreen" nel manifest dell'estensione. Ad esempio:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Disponibilità
Concetti e utilizzo
I service worker non hanno accesso al DOM e molti siti web hanno Content Security Policy che limitano la funzionalità degli script dei contenuti. L'API Offscreen consente all'estensione di utilizzare le API DOM in un documento nascosto senza interrompere l'esperienza utente aprendo nuove finestre o schede. L'API runtime è l'unica API per le estensioni supportata dai documenti fuori schermo.
Le pagine caricate come documenti fuori schermo vengono gestite in modo diverso rispetto ad altri tipi di pagine di estensione.
Le autorizzazioni dell'estensione vengono trasferite ai documenti fuori schermo, ma con limiti di accesso all'API dell'estensione. Ad esempio, poiché l'API browser.runtime è l'unica API di estensioni supportata dai documenti fuori schermo, la messaggistica deve essere gestita utilizzando i membri di questa API.
Di seguito sono riportati altri modi in cui i documenti fuori schermo si comportano in modo diverso dalle pagine normali:
- L'URL di un documento fuori schermo deve essere un file HTML statico incluso nell'estensione.
- I documenti fuori schermo non possono essere messi in primo piano.
- Un documento fuori schermo è un'istanza di
window, ma il valore della relativa proprietàopenerè semprenull. - Sebbene un pacchetto di estensioni possa contenere più documenti fuori schermo, un'estensione installata può averne solo uno aperto alla volta. Se l'estensione è in esecuzione in modalità divisa con un profilo di navigazione in incognito attivo, i profili normale e di navigazione in incognito possono avere ciascuno un documento fuori schermo.
Utilizza browser.offscreen.createDocument() e browser.offscreen.closeDocument() per creare e chiudere un documento fuori schermo. createDocument() richiede il url del documento, un motivo e una giustificazione:
browser.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Motivi
Per un elenco dei motivi validi, consulta la sezione Motivi. I motivi vengono impostati durante la creazione del documento per determinarne la durata. Il motivo AUDIO_PLAYBACK imposta la chiusura del documento dopo 30 secondi senza riproduzione audio. Tutti gli altri motivi non impostano limiti di durata.
Esempi
Gestire il ciclo di vita di un documento fuori schermo
L'esempio seguente mostra come assicurarsi che esista un documento fuori schermo. La chiamata di funzione setupOffscreenDocument() chiama runtime.getContexts() per trovare un documento fuori schermo esistente o lo crea se non esiste già.
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;
}
}
Prima di inviare un messaggio a un documento fuori schermo, chiama setupOffscreenDocument() per assicurarti che il documento esista, come mostrato nell'esempio seguente.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Per esempi completi, consulta le demo offscreen-clipboard e offscreen-dom su GitHub.
Prima di Chrome 116: controlla se è aperto un documento fuori schermo
runtime.getContexts() è stato aggiunto in Chrome 116. Nelle versioni precedenti di Chrome, utilizza clients.matchAll() per verificare la presenza di un documento fuori schermo esistente:
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);
});
}
}
Tipi
CreateParameters
Proprietà
-
giustificazione
stringa
Una stringa fornita dallo sviluppatore che spiega in modo più dettagliato la necessità del contesto in background. Lo user agent _può_ utilizzarlo per la visualizzazione all'utente.
-
motivi
Motivo[]
I motivi per cui l'estensione sta creando il documento fuori schermo.
-
url
stringa
L'URL (relativo) da caricare nel documento.
Reason
Enum
"TESTING"
Un motivo utilizzato solo a scopo di test.
"AUDIO_PLAYBACK"
Specifica che il documento fuori schermo è responsabile della riproduzione dell'audio.
"IFRAME_SCRIPTING"
Specifica che il documento fuori schermo deve incorporare e creare uno script per un iframe per modificarne i contenuti.
"DOM_SCRAPING"
Specifica che il documento fuori schermo deve incorporare un iframe e fare lo scraping del relativo DOM per estrarre informazioni.
"BLOBS"
Specifica che il documento fuori schermo deve interagire con gli oggetti Blob (incluso URL.createObjectURL()).
"DOM_PARSER"
Specifica che il documento fuori schermo deve utilizzare l'API DOMParser.
"USER_MEDIA"
Specifica che il documento fuori schermo deve interagire con gli stream multimediali dei contenuti multimediali dell'utente (ad es. getUserMedia()).
"DISPLAY_MEDIA"
Specifica che il documento fuori schermo deve interagire con gli stream multimediali dei contenuti multimediali visualizzati (ad es. getDisplayMedia()).
"WEB_RTC"
Specifica che il documento fuori schermo deve utilizzare le API WebRTC.
"CLIPBOARD"
Specifica che il documento fuori schermo deve interagire con l'API Clipboard.
"LOCAL_STORAGE"
Specifica che il documento fuori schermo deve accedere a localStorage.
"WORKERS"
Specifica che il documento fuori schermo deve generare worker.
"BATTERY_STATUS"
Specifica che il documento fuori schermo deve utilizzare navigator.getBattery.
"MATCH_MEDIA"
Specifica che il documento fuori schermo deve utilizzare window.matchMedia.
"GEOLOCATION"
Specifica che il documento fuori schermo deve utilizzare navigator.geolocation.
Metodi
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Chiude il documento fuori schermo attualmente aperto per l'estensione.
Resi
-
Promise<void>
Promise che si risolve quando il documento fuori schermo è stato chiuso.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Crea un nuovo documento fuori schermo per l'estensione.
Parametri
-
Parametri
I parametri che descrivono il documento fuori schermo da creare.
Resi
-
Promise<void>
Promise che si risolve quando il documento fuori schermo viene creato e ha completato il caricamento iniziale della pagina.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Determina se l'estensione ha un documento attivo.
Resi
-
Promise<boolean>
Promise che si risolve con il risultato che indica se l'estensione ha un documento fuori schermo attivo.