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 policy di sicurezza dei contenuti che limitano la funzionalità degli script di 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 offscreen.

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 chrome.runtime è l'unica API di estensione supportata dai documenti off-screen, 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 offscreen deve essere un file HTML statico incluso nell'estensione.
• Non è possibile mettere a fuoco i documenti fuori dallo schermo.
• Un documento fuori schermo è un'istanza di window, ma il valore della relativa proprietà opener è sempre null.
• Sebbene un pacchetto di estensioni possa contenere più documenti fuori schermo, un'estensione installata può averne aperto solo uno alla volta. Se l'estensione è in esecuzione in modalità split con un profilo di navigazione in incognito attivo, i profili normale 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 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 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 a vita.

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 o crea il documento 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 esempi completi, consulta le demo offscreen-clipboard e offscreen-dom su GitHub.

Prima di Chrome 116: controllare 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 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>