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"
],
...
}
Disponibilité
Concepts et utilisation
Les service workers ne disposent pas d'un accès DOM, et de nombreux sites Web appliquent des règles de sécurité du contenu qui
limiter les fonctionnalités des scripts de contenu. L'API Offscreen permet à l'extension d'utiliser le DOM
des API dans un document caché sans interrompre l'expérience utilisateur en ouvrant de nouvelles fenêtres ou
onglets. L'API runtime
est la seule API Extensions
des 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 conservées dans des documents hors écran, mais avec des limites sur l'API d'extension
y accéder. Par exemple, comme l'API chrome.runtime
est la seule
API des extensions compatible avec les documents hors écran, la messagerie doit être gérée
à l'aide des membres de cette API.
Voici d'autres façons 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 avec 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 n'en avoir qu'un ouvert à la fois. Si l'extension est en cours d'exécution en mode partagé avec un profil de navigation privée actif, les profils normal et navigation privée peuvent chacun avoir un document hors écran.
Utiliser chrome.offscreen.createDocument()
et
chrome.offscreen.closeDocument()
pour créer et fermer une fenêtre hors écran
document. 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 pendant
création du document pour déterminer sa durée de vie. Le motif AUDIO_PLAYBACK
définit
pour fermer le document au bout de 30 secondes sans lecture audio. Toutes les autres raisons ne définissent pas de limite de durée de vie.
Exemples
Maintenir le cycle de vie d'un document hors écran
L'exemple suivant montre comment s'assurer qu'un document hors écran existe. La
La fonction setupOffscreenDocument()
appelle runtime.getContexts()
pour trouver
un document hors écran existant ou crée le document s'il n'existe pas encore.
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 vers 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 sections hors écran du presse-papiers 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 précédentes 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é du contexte d'arrière-plan. Le user-agent _may_ l'utilisera 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
Énumération
"TEST"
Motif utilisé à des fins de test uniquement.
"AUDIO_PLAYBACK"
Spécifie que le document hors écran est responsable de la lecture du contenu audio.
"IFRAME_SCRIPTING"
Spécifie que le document hors écran doit intégrer un iFrame et créer un script pour en modifier le contenu.
"DOM_SCRAPING"
Spécifie que le document hors écran doit intégrer un iFrame et extraire des informations de son DOM pour extraire des informations.
"BLOBS"
Spécifie que le document hors écran doit interagir avec les 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 utilisateurs (par exemple, getUserMedia()
).
"DISPLAY_MEDIA"
Spécifie que le document hors écran doit interagir avec les flux multimédias d'éléments multimédias display (par exemple, getDisplayMedia()
).
"WEB_RTC"
Spécifie que le document hors écran doit utiliser les API WebRTC.
"CLIPBOARD"
Spécifie que le document hors écran doit interagir avec l'API Clipboard.
"LOCAL_STORAGE"
Spécifie que le document hors écran doit avoir accès à 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"
Spécifie que le document hors écran doit utiliser window.matchMedia.
"GEOLOCATION"
Spécifie 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
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promesse<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promesse<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.