chrome.offscreen

Descrizione

Autorizzazioni

Per 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 criteri di sicurezza dei contenuti 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 delle 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 estensioni. Le autorizzazioni dell'estensione vengono trasferite anche ai documenti fuori schermo, ma con limiti di accesso all'API dell'estensione. Ad esempio, poiché l'API chrome.runtime è l'unica API di estensione supportata dai documenti fuori schermo, la messaggistica deve essere gestita utilizzando i membri di quell'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 associato all'estensione.
• Non è possibile impostare lo stato attivo sui documenti fuori schermo.
• Un documento fuori schermo è un'istanza di window, ma il valore della relativa proprietà opener è sempre null.
• Anche se un pacchetto di estensioni può contenere più documenti fuori schermo, un'estensione installata può aprirne solo uno alla volta. Se l'estensione viene eseguita in modalità suddivisa con un profilo di navigazione in incognito attivo, i profili normali e di navigazione in incognito possono avere ciascuno un documento fuori schermo.

Utilizza chrome.offscreen.createDocument() e chrome.offscreen.closeDocument() per creare e chiudere un documento fuori schermo. createDocument() richiede il url del documento, un motivo e una giustificazione:

chrome.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 determinare la sua durata. Il motivo AUDIO_PLAYBACK imposta la chiusura del documento dopo 30 secondi senza riproduzione audio. Tutti gli altri motivi non impostano limiti per l'intera durata.

Esempi

Mantenere il ciclo di vita di un documento fuori schermo

L'esempio seguente mostra come assicurarsi che esista un documento fuori schermo. La funzione setupOffscreenDocument() chiama runtime.getContexts() per trovare un documento fuori schermo esistente oppure 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 = 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;
  }
}

Prima di inviare un messaggio a un documento fuori schermo, chiama setupOffscreenDocument() per assicurarti che il documento esista, come mostrato nell'esempio seguente.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Per un esempio completo, guarda le demo offscreen-clipboard e offscreen-dom su GitHub.

Prima di Chrome 116: controllare se un documento fuori schermo è aperto

L'app runtime.getContexts() è stata aggiunta 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 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,
)