Description
Utilisez l'API offscreen
pour créer et gérer des documents hors écran.
Autorisations
offscreen
Pour utiliser l'API Offscreen, déclarez l'autorisation "offscreen"
dans le fichier manifeste de l'extension. Exemple :
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Garantie de disponibilité
Concepts et utilisation
Les service workers n'ont pas d'accès DOM et de nombreux sites Web disposent de règles de sécurité du contenu qui limitent le fonctionnement 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 traitées différemment des autres types de pages d'extension.
Les autorisations de l'extension sont transférées sur les documents hors écran, mais l'accès aux API de l'extension est limité. Par exemple, comme l'API chrome.runtime
est la seule API d'extension compatible avec les documents hors écran, la messagerie doit être gérée à l'aide des membres de cette API.
Voici d'autres manières dont les documents hors écran se comportent différemment des pages normales:
- L'URL d'un document hors écran doit être un fichier HTML statique associé à l'extension.
- Impossible de sélectionner des documents hors écran.
- Un document hors écran est une instance de
window
, mais la valeur de sa propriétéopener
est toujoursnull
. - 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. La méthode createDocument()
requiert l'url
du document, un motif et une justification:
chrome.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Raisons
Pour obtenir la liste des raisons valides, consultez la section Motifs. Les raisons sont définies lors de la création du document pour déterminer sa durée de vie. Le motif AUDIO_PLAYBACK
définit le document à se fermer au bout de 30 secondes sans lecture audio. Pour les autres raisons, aucune limite à vie n'est définie.
Exemples
Maintenir le cycle de vie d'un document hors écran
L'exemple suivant montre comment vérifier qu'un document hors écran existe. La fonction setupOffscreenDocument()
appelle runtime.getContexts()
pour rechercher un document existant hors écran 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 = 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 de 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 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);
});
}
}
Types
CreateParameters
Propriétés
-
justification
chaîne
Chaîne fournie par le développeur qui explique plus en détail la nécessité d'un contexte d'arrière-plan. Le user-agent _peut_ l'utiliser dans l'affichage pour l'utilisateur.
-
raisons
Motif[]
La ou les raisons pour lesquelles l'extension crée le document hors écran.
-
url
chaîne
URL (relative) à charger dans le document.
Reason
Enum
"TEST"
Un motif utilisé uniquement à des fins de test.
"AUDIO_PLAYBACK"
Indique que le document hors écran est responsable de la lecture audio.
"IFrame_SCRIPTING"
Indique que le document hors écran doit intégrer un iFrame et en créer un script pour que vous puissiez modifier le contenu de l'iFrame.
"DOM_SCRAPING"
Indique que le document hors écran doit intégrer un iFrame et scraper son DOM pour en extraire les informations.
"BLOBS"
Indique que le document hors écran doit interagir avec des objets Blob (y compris URL.createObjectURL()
).
"DOM_PARSER"
Indique que le document hors écran doit utiliser l'API DOM Parser.
"USER_MEDIA"
Indique que le document hors écran doit interagir avec les flux multimédias provenant 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 display (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 Presse-papiers.
"LOCAL_STORAGE"
Indique que le document hors écran doit pouvoir accéder à localStorage.
"WORKERS"
Indique que le document hors écran doit générer les workers.
"BATTERY_STATUS"
Indique 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()
chrome.offscreen.closeDocument(
callback?: function,
)
Ferme le document hors écran actuellement ouvert pour l'extension.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
Crée un document hors écran pour l'extension.
Paramètres
-
paramètres
Paramètres décrivant le document hors écran à créer.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.