Description
Utilisez l'API offscreen pour créer et gérer des documents hors écran.
Autorisations
offscreenPour 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 ont des règles de sécurité du contenu qui limitent les fonctionnalités des scripts de contenu. L'API Offscreen permet à l'extension d'utiliser les 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 reportées sur les documents hors écran, mais avec des limites d'accès à l'API de l'extension. Par exemple, étant donné que l'API browser.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 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 sélectionnés.
- Un document hors écran est une instance de
window, mais la valeur de sa propriétéopenerest toujoursnull. - Bien qu'un package d'extension puisse contenir plusieurs documents hors écran, une extension installée ne peut en ouvrir qu'un seul à 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 browser.offscreen.createDocument() et browser.offscreen.closeDocument() pour créer et fermer un document hors écran. createDocument() nécessite l'url du document, un motif et une justification :
browser.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. La raison AUDIO_PLAYBACK définit la fermeture du document après 30 secondes sans lecture audio. Aucun autre motif ne définit de limite 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 crée le document 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 = browser.runtime.getURL(path);
const existingContexts = await browser.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
if (existingContexts.length > 0) {
return;
}
// create offscreen document
if (creating) {
await creating;
} else {
creating = browser.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.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.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 rechercher un document hors écran existant :
async function hasOffscreenDocument() {
if ('getContexts' in browser.runtime) {
const contexts = await browser.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(browser.runtime.id);
});
}
}
Types
CreateParameters
Propriétés
-
justification
chaîne
Chaîne fournie par le développeur qui explique plus en détail la nécessité du contexte d'arrière-plan. Le user-agent _peut_ l'utiliser pour l'affichage à l'utilisateur.
-
raisons
Reason[]
La ou les raisons pour lesquelles l'extension crée le document hors écran.
-
url
chaîne
URL (relative) à charger dans le document.
Reason
Énumération
"TESTING"
Motif utilisé uniquement à des fins de test.
"AUDIO_PLAYBACK"
Indique que le document hors écran est responsable de la lecture audio.
"IFRAME_SCRIPTING"
Spécifie que le document hors écran doit intégrer et scripter un iFrame pour modifier son contenu.
"DOM_SCRAPING"
Spécifie que le document hors écran doit intégrer un iFrame et scraper son DOM pour extraire des informations.
"BLOBS"
Indique que le document hors écran doit interagir avec des objets Blob (y compris URL.createObjectURL()).
"DOM_PARSER"
Spécifie que le document hors écran doit utiliser l'API DOMParser.
"USER_MEDIA"
Spécifie que le document hors écran doit interagir avec les flux multimédias des contenus multimédias de l'utilisateur (par exemple, getUserMedia()).
"DISPLAY_MEDIA"
Indique que le document hors écran doit interagir avec les flux multimédias des supports d'affichage (par exemple, getDisplayMedia()).
"WEB_RTC"
Indique que le document hors écran doit utiliser les API WebRTC.
"CLIPBOARD"
Indique que le document hors écran doit interagir avec l'API Clipboard.
"LOCAL_STORAGE"
Spécifie que le document hors écran doit accéder à localStorage.
"WORKERS"
Spécifie que le document hors écran doit générer des workers.
"BATTERY_STATUS"
Spécifie que le document hors écran doit utiliser navigator.getBattery.
"MATCH_MEDIA"
Indique que le document hors écran doit utiliser window.matchMedia.
"GEOLOCATION"
Indique que le document hors écran doit utiliser navigator.geolocation.
Méthodes
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Ferme le document hors écran actuellement ouvert pour l'extension.
Renvoie
-
Promise<void>
Promesse qui se résout lorsque le document hors écran a été fermé.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Crée un document hors écran pour l'extension.
Paramètres
-
paramètres
Paramètres décrivant le document hors écran à créer.
Renvoie
-
Promise<void>
Promesse qui se résout lorsque le document hors écran est créé et que le chargement de page initial est terminé.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Détermine si l'extension comporte un document actif.
Renvoie
-
Promise<boolean>
Promesse qui se résout avec le résultat indiquant si l'extension dispose d'un document hors écran actif.