chrome.offscreen

Description

Autorisations

Pour utiliser l'API Offscreen, déclarez l'autorisation "offscreen" dans le fichier manifeste de l'extension. Exemple :

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

Disponibilité

Concepts et utilisation

Les service workers n'ont pas accès au DOM, et de nombreux sites Web disposent de règles de sécurité du contenu qui limitent les fonctionnalités des scripts de contenu. L'API Offscreen permet à l'extension d'utiliser des API DOM dans un document masqué sans interrompre l'expérience utilisateur en ouvrant de nouvelles fenêtres ou de nouveaux onglets. L'API runtime est la seule API d'extensions compatible avec les documents hors écran.

Les pages chargées en tant que documents hors écran sont gérées différemment des autres types de pages d'extension. Les autorisations de l'extension sont transférées aux documents hors écran, mais avec des limites d'accès à l'API d'extension. Par exemple, comme l'API chrome.runtime est la seule API d'extensions compatible avec les documents hors écran, la messagerie doit être gérée à l'aide des membres de cette API.

Voici d'autres différences de comportement entre les documents hors écran et les pages normales :

• L'URL d'un document hors écran doit être un fichier HTML statique fourni avec l'extension.
• Les documents hors écran ne peuvent pas être mis en avant.
• Un document hors écran est une instance de window, mais la valeur de sa propriété opener est toujours null.
• Bien qu'un package d'extension puisse contenir plusieurs documents hors écran, une extension installée ne peut en avoir qu'un seul ouvert à la fois. Si l'extension s'exécute en mode fractionné avec un profil de navigation privée actif, les profils normal et de navigation privée peuvent chacun avoir un document hors écran.

Utilisez chrome.offscreen.createDocument() et chrome.offscreen.closeDocument() pour créer et fermer un document hors écran. createDocument() nécessite l'url du document, un motif et une justification :

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

Motifs

Pour obtenir la liste des motifs valides, consultez la section Motifs. Les motifs sont définis lors de la création du document pour déterminer sa durée de vie. Le motif AUDIO_PLAYBACK définit la fermeture du document après 30 secondes sans lecture audio. Tous les autres motifs ne définissent pas de limites de durée de vie.

Exemples

Gérer le cycle de vie d'un document hors écran

L'exemple suivant montre comment s'assurer qu'un document hors écran existe. La fonction setupOffscreenDocument() appelle runtime.getContexts() pour rechercher un document hors écran existant ou le créer s'il n'existe pas déjà.

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

Avant d'envoyer un message à un document hors écran, appelez setupOffscreenDocument() pour vous assurer que le document existe, comme illustré dans l'exemple suivant.

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

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

Pour obtenir des exemples complets, consultez les démonstrations offscreen-clipboard et offscreen-dom sur GitHub.

Avant Chrome 116 : vérifier si un document hors écran est ouvert

runtime.getContexts() a été ajouté dans Chrome 116. Dans les versions antérieures de Chrome, utilisez clients.matchAll() pour vérifier si un document hors écran existe :

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>

chrome.offscreen.hasDocument(): Promise<boolean>