chrome.offscreen

Descrizione

Usa l'API offscreen per creare e gestire documenti fuori schermo.

Autorizzazioni

offscreen

Per utilizzare l'API Offscreen, dichiara l'autorizzazione "offscreen" nel manifest dell'estensione. Ad esempio:

{
  "name": "My extension",
  ...
  "permissions": [
    "offscreen"
  ],
  ...
}

Disponibilità

Chrome 109 e versioni successive MV3 o versioni successive

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);
    });
  }
}

Tipi

CreateParameters

Proprietà

• giustificazione

  stringa

  Una stringa fornita dallo sviluppatore che spiega, in modo più dettagliato, la necessità del contesto di sfondo. Lo user agent _può_ usarla quando viene mostrata all'utente.

• motivi

  Motivo[]

  Il motivo o i motivi per cui l'estensione sta creando il documento fuori schermo.

• url

  stringa

  L'URL (relativo) da caricare nel documento.

Reason

Enum

"TEST"
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 poter modificare i contenuti dell'iframe.

"DOM_SCRAPING"
Specifica che il documento fuori schermo deve incorporare un iframe ed eseguire lo scraping del DOM per estrarre le 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 degli elementi multimediali display (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 richiede l'accesso a localStorage.

"WORKERS"
Specifica che il documento fuori schermo deve riprodurre i lavoratori.

"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()

Promesso .

chrome.offscreen.closeDocument(
  callback?: function,
)

Chiude il documento fuori schermo attualmente aperto per l'estensione.

Parametri

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promesso<void>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

createDocument()

Promesso .

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

Crea un nuovo documento fuori schermo per l'estensione.

Parametri

• Parametri

  CreateParameters

  I parametri che descrivono il documento fuori schermo da creare.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promesso<void>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.