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 del contenuto che limitano la funzionalità degli script di contenuti. L'API Offscreen consente all'estensione di usare il DOM le API in un documento nascosto senza interrompere l'esperienza utente aprendo nuove finestre o schede. L'API runtime è l'unica API delle estensioni supportate 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 ai documenti fuori schermo, ma con dei limiti sull'API dell'estensione l'accesso. Ad esempio, perché l'API chrome.runtime è l'unica l'API delle estensioni supportata da documenti fuori schermo, è necessario gestire i messaggi 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 abbinato all'estensione.
• Impossibile impostare lo stato attivo sui documenti fuori schermo.
• Un documento fuori schermo è un'istanza di window, ma il valore della sua proprietà opener è sempre null.
• Un pacchetto di estensione può contenere più documenti fuori schermo, ma un'estensione installata può aprirne uno alla volta. Se l'estensione è in esecuzione in modalità divisa con un profilo di navigazione in incognito attivo, i profili normale e in incognito possono avere un documento fuori schermo.

Utilizza chrome.offscreen.createDocument() e chrome.offscreen.closeDocument() per creare e chiudere un fuori schermo documento. createDocument() richiede l'elemento 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 di motivi validi, consulta la sezione Motivi. I motivi vengono impostati durante creazione di documenti per determinarne la durata. Il motivo AUDIO_PLAYBACK imposta la documento da chiudere dopo 30 secondi senza riproduzione audio. Tutti gli altri motivi non impostano limiti di durata.

Esempi

Mantieni il ciclo di vita di un documento fuori schermo

L'esempio seguente mostra come garantire l'esistenza di un documento fuori schermo. La La funzione setupOffscreenDocument() chiama runtime.getContexts() per trovare documento esistente fuori schermo 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 il numero setupOffscreenDocument() per verificare esiste, come illustrato 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, guarda gli appunti fuori schermo e demo offscreen-dom su GitHub.

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

runtime.getContexts() è stato aggiunto in Chrome 116. Nelle versioni precedenti di Chrome, usa 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,
)