Description
Utilisez l'API chrome.runtime
pour récupérer le service worker, renvoyer des informations sur le fichier manifeste, écouter les événements du cycle de vie de l'extension et y répondre. Vous pouvez également utiliser cette API pour convertir le chemin relatif d'URL en URL complètes.
Présentation
L'API Runtime fournit des méthodes permettant d'assurer un certain nombre de fonctionnalités que vos extensions peuvent utiliser:
- Transmission du message
- Votre extension peut communiquer avec différents contextes au sein de votre extension et avec d'autres extensions à l'aide des méthodes et événements suivants : connect(), onConnect, onConnectExternal, sendMessage(), onMessage et onMessageExternal. En outre, votre extension peut transmettre des messages aux applications natives sur l'appareil de l'utilisateur à l'aide de connectNative() et sendNativeMessage().
- Accéder aux métadonnées des extensions et de la plate-forme
- Ces méthodes vous permettent de récupérer plusieurs métadonnées spécifiques concernant l'extension et la plate-forme. Les méthodes de cette catégorie incluent getManifest() et getPlatformInfo().
- Gérer le cycle de vie et les options des extensions
- Ces propriétés vous permettent d'effectuer des méta-opérations sur l'extension et d'afficher la page d'options. Les méthodes et événements de cette catégorie incluent onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() et setDésinstallerURL().
- Utilitaires d'assistance
- Ces méthodes sont utiles, par exemple pour convertir des représentations de ressources internes en formats externes. Les méthodes de cette catégorie incluent getURL().
- Utilitaires du mode Kiosque
- Ces méthodes ne sont disponibles que sur ChromeOS et existent principalement pour des mises en œuvre en mode kiosque. Les méthodes de cette catégorie incluent restart et restartAfterDelay.
Autorisations
La plupart des méthodes de l'API Runtime ne nécessitent aucune autorisation, à l'exception de sendNativeMessage et connectNative qui nécessitent l'autorisation nativeMessaging
.
Manifest
L'exemple suivant montre comment déclarer l'autorisation nativeMessaging
dans le fichier manifeste:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Cas d'utilisation
Ajouter une image à une page Web
Pour qu'une page Web puisse accéder à un élément hébergé sur un autre domaine, elle doit spécifier l'URL complète de la ressource (par exemple, <img src="https://example.com/logo.png">
). Il en va de même pour l'ajout d'un élément d'extension sur une page Web. Les deux différences sont les suivantes : les éléments de l'extension doivent être exposés en tant que ressources accessibles sur le Web et les scripts de contenu sont généralement chargés d'injecter des éléments d'extension.
Dans cet exemple, l'extension ajoute logo.png
à la page dans laquelle le script de contenu est injecté en utilisant runtime.getURL()
pour créer une URL complète. Avant toute chose, l'élément doit être déclaré dans le fichier manifeste en tant que ressource accessible sur le Web.
manifest.json:
{
...
"web_accessible_resources": [
{
"resources": [ "logo.png" ],
"matches": [ "https://*/*" ]
}
],
...
}
content.js:
{ // Block used to avoid setting global variables
const img = document.createElement('img');
img.src = chrome.runtime.getURL('logo.png');
document.body.append(img);
}
Envoyer des données du service worker à un script de contenu
Il est courant que les scripts de contenu d'une extension aient besoin de données gérées par une autre partie de l'extension, comme le service worker. Tout comme deux fenêtres de navigateur ouvertes sur la même page Web, ces deux contextes ne peuvent pas accéder directement aux valeurs de l'autre. Au lieu de cela, l'extension peut utiliser la transmission de messages pour se coordonner entre ces différents contextes.
Dans cet exemple, le script de contenu a besoin de données du service worker de l'extension pour initialiser son UI. Pour obtenir ces données, il transmet un message get-user-data
au service worker et répond avec une copie des informations de l'utilisateur.
content.js:
// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
// 3. Got an asynchronous response with the data from the service worker
console.log('received user data', response);
initializeUI(response);
});
background.js:
// Example of a simple user data object
const user = {
username: 'demo-user'
};
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
// 2. A page requested user data, respond with a copy of `user`
if (message === 'get-user-data') {
sendResponse(user);
}
});
Recueillez des commentaires sur la désinstallation
De nombreuses extensions utilisent des enquêtes post-désinstallation pour comprendre comment une extension pourrait mieux répondre aux besoins de ses utilisateurs et améliorer la fidélisation. L'exemple suivant montre comment ajouter cette fonctionnalité.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
Exemples d'extensions
Consultez la démonstration Manifest V3 – Ressources accessibles sur le Web pour obtenir d'autres exemples d'API Runtime.
Types
ContextFilter
Filtre permettant d'établir une correspondance avec certains contextes d'extension. Les contextes correspondants doivent correspondre à tous les filtres spécifiés. Tout filtre non spécifié correspond à tous les contextes disponibles. Ainsi, un filtre {} correspondra à tous les contextes disponibles.
Propriétés
-
contextIds
string[] facultatif
-
contextTypes
ContextType[] facultatif
-
documentIds
string[] facultatif
-
documentOrigins
string[] facultatif
-
documentUrls
string[] facultatif
-
frameIds
number[] facultatif
-
navigation privée
Booléen facultatif
-
tabIds
number[] facultatif
-
windowIds
number[] facultatif
ContextType
Enum
"TAB"
Spécifie le type de contexte en tant qu'onglet
"POPUP"
Spécifie le type de contexte en tant que fenêtre pop-up d'extension.
"BACKGROUND"
Spécifie le type de contexte en tant que service worker.
"OFFSCREEN_DOCUMENT"
Spécifie le type de contexte en tant que document hors écran.
"SIDE_PANEL"
Spécifie le type de contexte en tant que panneau latéral.
ExtensionContext
Contexte pour l'hébergement du contenu de l'extension.
Propriétés
-
contextId
chaîne
Identifiant unique pour ce contexte
-
contextType
Type de contexte auquel cela correspond.
-
documentId
string facultatif
UUID du document associé à ce contexte, ou non défini si ce contexte n'est pas hébergé dans un document.
-
documentOrigin
string facultatif
Origine du document associé à ce contexte, ou non définie si le contexte n'est pas hébergé dans un document.
-
documentUrl
string facultatif
URL du document associé à ce contexte, ou non définie si le contexte n'est pas hébergé dans un document.
-
frameId
Nombre
ID du frame pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans un frame.
-
navigation privée
boolean
Indique si le contexte est associé à un profil de navigation privée.
-
tabId
Nombre
ID de l'onglet pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans un onglet.
-
windowId
Nombre
ID de la fenêtre pour ce contexte, ou -1 si ce contexte n'est pas hébergé dans une fenêtre.
MessageSender
Objet contenant des informations sur le contexte du script ayant envoyé un message ou une requête.
Propriétés
-
documentId
string facultatif
Chrome 106 et versions ultérieuresUUID du document qui a ouvert la connexion.
-
documentLifecycle
string facultatif
Chrome 106 et versions ultérieuresCycle de vie du document qui a ouvert la connexion au moment de la création du port. Notez que l'état du cycle de vie du document peut avoir changé depuis la création du port.
-
frameId
numéro facultatif
Cadre ayant ouvert la connexion. 0 pour les cadres de premier niveau, positif pour les cadres enfants. Il ne sera défini que lorsque
tab
est défini. -
id
string facultatif
ID de l'extension qui a ouvert la connexion, le cas échéant.
-
nativeApplication
string facultatif
Chrome 74 et versions ultérieuresNom de l'application native qui a ouvert la connexion, le cas échéant.
-
origine
string facultatif
Chrome 80 et versions ultérieuresOrigine de la page ou du cadre à l'origine de l'ouverture de la connexion. Elle peut différer de la propriété d'URL (par exemple, about:blank) ou être opaque (par exemple, des iFrames en bac à sable). Cela permet de déterminer si l'origine est fiable lorsque l'URL ne permet pas de la déterminer immédiatement.
-
tab
Tabulation facultatif
Le
tabs.Tab
qui a ouvert la connexion, le cas échéant. Cette propriété n'est présente que lorsque la connexion a été ouverte à partir d'un onglet (y compris des scripts de contenu), et uniquement si le récepteur est une extension et non une application. -
tlsChannelId
string facultatif
ID du canal TLS de la page ou du cadre ayant ouvert la connexion, si l'extension l'exige et, le cas échéant.
-
url
string facultatif
URL de la page ou du cadre qui a ouvert la connexion. Si l'expéditeur est dans un iFrame, il s'agit de l'URL de l'iFrame, et non de celle de la page qui l'héberge.
OnInstalledReason
Motif de l'envoi de cet événement.
Enum
"install"
Spécifie le motif de l'événement en tant qu'installation.
"update"
Spécifie le motif de l'événement en tant que mise à jour d'extension.
"chrome_update"
Spécifie le motif de l'événement en tant que mise à jour de Chrome.
"shared_module_update"
Spécifie le motif de l'événement en tant que mise à jour d'un module partagé.
OnRestartRequiredReason
Motif de l'envoi de l'événement. "app_update" est utilisé lorsque le redémarrage est nécessaire, car l'application est mise à jour vers une version plus récente. "os_update" est utilisé lorsque le redémarrage est nécessaire, car le navigateur/l'OS a été mis à jour vers une version plus récente. La valeur "periodic" est utilisée lorsque le temps d'exécution du système dépasse le temps d'activité autorisé défini dans la règle d'entreprise.
Enum
"app_update"
Spécifie le motif de l'événement en tant que mise à jour de l'application.
"os_update"
Spécifie le motif de l'événement en tant que mise à jour du système d'exploitation.
"periodic"
Spécifie le motif de l'événement comme un redémarrage périodique de l'application.
PlatformArch
Architecture du processeur de la machine.
Enum
"arm"
Spécifie l'architecture de traitement en tant que "arm".
"arm64"
Spécifie l'architecture de traitement en tant que arm64.
"x86-32"
Spécifie l'architecture de traitement sous la forme x86-32.
"x86-64"
Spécifie l'architecture de traitement sous la forme x86-64.
"mips"
Spécifie l'architecture du processeur en mips.
"mips64"
Spécifie l'architecture du processeur en tant que mips64.
PlatformInfo
Objet contenant des informations sur la plate-forme actuelle.
Propriétés
-
arche
Architecture du processeur de la machine.
-
nacl_arch
Architecture du client natif. Celui-ci peut être différent de celui d'arche sur certaines plates-formes.
-
os
Système d'exploitation sur lequel Chrome est exécuté.
PlatformNaclArch
Architecture du client natif. Celui-ci peut être différent de celui d'arche sur certaines plates-formes.
Enum
"arm"
Spécifie l'architecture du client natif en tant qu'arm.
"x86-32"
Spécifie l'architecture cliente native en tant que x86-32.
"x86-64"
Spécifie l'architecture cliente native en tant que x86-64.
"mips"
Spécifie l'architecture du client natif en mips.
"mips64"
Spécifie l'architecture cliente native en tant que mips64.
PlatformOs
Système d'exploitation sur lequel Chrome est exécuté.
Enum
"mac"
Spécifie le système d'exploitation macOS.
"win"
Spécifie le système d'exploitation Windows.
"android"
Spécifie le système d'exploitation Android.
"cros"
Spécifie le système d'exploitation Chrome.
"linux"
Spécifie le système d'exploitation Linux.
"openbsd"
Spécifie le système d'exploitation OpenBSD.
"fuchsia"
Spécifie le système d'exploitation Fuchsia.
Port
Objet qui permet une communication bidirectionnelle avec d'autres pages. Pour en savoir plus, consultez la section Connexions de longue durée.
Propriétés
-
name
chaîne
Nom du port, tel que spécifié dans l'appel de
runtime.connect
. -
onDisconnect
Événement<functionvoidvoid>
Déclenché lorsque le port est déconnecté des autres extrémités
runtime.lastError
peut être défini si le port a été déconnecté par erreur. Si le port est fermé via disconnect, cet événement est uniquement déclenché à l'autre extrémité. Cet événement est déclenché au maximum une fois (voir aussi Durée de vie du port).La fonction
onDisconnect.addListener
se présente comme suit :(callback: function) => {...}
-
onMessage
Événement<functionvoidvoid>
Cet événement est déclenché lorsque postMessage est appelé par l'autre extrémité du port.
La fonction
onMessage.addListener
se présente comme suit :(callback: function) => {...}
-
expéditeur
MessageSender facultatif
Cette propriété sera présente uniquement sur les ports transmis aux écouteurs onConnect / onConnectExternal / onConnectNative.
-
dissocier
void
Déconnectez immédiatement le port. L'appel de
disconnect()
sur un port déjà déconnecté n'a aucun effet. Lorsqu'un port est déconnecté, aucun nouvel événement n'est envoyé à ce port.La fonction
disconnect
se présente comme suit :() => {...}
-
postMessage
void
Envoyez un message à l'autre extrémité du port. Si le port est déconnecté, une erreur est générée.
La fonction
postMessage
se présente comme suit :(message: any) => {...}
-
message
toutes
Chrome 52 ou version ultérieureMessage à envoyer. Cet objet doit être au format JSON.
-
RequestUpdateCheckStatus
Résultat de la vérification des mises à jour.
Enum
"throttled"
Indique que la vérification de l'état a été limitée. Cela peut se produire si vous effectuez plusieurs vérifications dans un court laps de temps.
"no_update"
Indique qu'aucune mise à jour n'est disponible à installer.
"update_available"
Indique qu'une mise à jour peut être installée.
Propriétés
id
ID de l'extension ou de l'application.
Type
chaîne
lastError
Renseigné avec un message d'erreur en cas d'échec de l'appel d'une fonction API ; sinon non défini. Elle n'est définie que dans le champ d'application du rappel de cette fonction. Si une erreur est générée, mais qu'aucun accès à runtime.lastError
n'est effectué dans le rappel, un message est consigné dans la console et indique la fonction API ayant généré l'erreur. Les fonctions d'API qui renvoient des promesses ne définissent pas cette propriété.
Type
objet
Propriétés
-
message
string facultatif
Détails concernant l'erreur qui s'est produite.
Méthodes
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
Tente de connecter des écouteurs au sein d'une extension (comme la page en arrière-plan) ou d'autres extensions/applications. Cette fonctionnalité est utile pour les scripts de contenu qui se connectent à leurs processus d'extension, pour la communication entre les applications et les extensions, et pour la messagerie Web. Notez que cela ne se connecte à aucun écouteur dans un script de contenu. Les extensions peuvent se connecter aux scripts de contenu intégrés dans les onglets via tabs.connect
.
Paramètres
-
extensionId
string facultatif
ID de l'extension à laquelle se connecter. Si cette valeur est omise, une tentative de connexion sera effectuée avec votre propre extension. Obligatoire si vous envoyez des messages à partir d'une page Web pour la messagerie Web.
-
connectInfo
objet facultatif
-
includeTlsChannelId
Booléen facultatif
Indique si l'ID du canal TLS est transmis à onConnectExternal pour les processus qui écoutent l'événement de connexion.
-
name
string facultatif
Sera transmis à onConnect pour les processus qui écoutent l'événement de connexion.
-
Renvoie
-
Port par lequel les messages peuvent être envoyés et reçus. L'événement onDisconnect du port est déclenché si l'extension n'existe pas.
connectNative()
chrome.runtime.connectNative(
application: string,
)
Se connecte à une application native sur la machine hôte. Cette méthode nécessite l'autorisation "nativeMessaging"
. Pour en savoir plus, consultez l'article Message natif.
Paramètres
-
application
chaîne
Nom de l'application enregistrée à laquelle se connecter.
Renvoie
-
Port par lequel les messages peuvent être envoyés et reçus avec l'application
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Récupère l'objet "window" JavaScript de la page en arrière-plan exécutée dans l'extension ou l'application actuelle. Si la page en arrière-plan est une page d'événement, le système s'assure qu'elle est chargée avant d'appeler le rappel. En l'absence de page en arrière-plan, une erreur est générée.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(backgroundPage?: Window) => void
-
backgroundPage
Fenêtre facultatif
Objet JavaScript "window" (fenêtre) pour la page d'arrière-plan.
-
Renvoie
-
Promise<Window | undefined>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Récupère des informations sur les contextes actifs associés à cette extension.
Paramètres
-
filtre
Un filtre permettant de trouver des contextes correspondants. Un contexte correspond s'il correspond à tous les champs spécifiés dans le filtre. Tout champ non spécifié du filtre correspond à tous les contextes.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(contexts: ExtensionContext[]) => void
-
contexts
Contextes correspondants, le cas échéant.
-
Renvoie
-
Promise<ExtensionContext[]>
Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getManifest()
chrome.runtime.getManifest()
Affiche des informations sur l'application ou l'extension à partir du fichier manifeste. L'objet renvoyé est une sérialisation du fichier manifeste complet.
Renvoie
-
objet
Détails du fichier manifeste
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
Renvoie une entrée DirectoryEntry pour le répertoire de package.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Renvoie
-
Promise<DirectoryEntry>
Chrome 122 ou version ultérieureLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Affiche des informations sur la plate-forme actuelle.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(platformInfo: PlatformInfo) => void
-
platformInfo
-
Renvoie
-
Promise<PlatformInfo>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getURL()
chrome.runtime.getURL(
path: string,
)
Convertit un chemin d'accès relatif contenu dans un répertoire d'installation d'application ou d'extension en URL complète.
Paramètres
-
chemin d'accès
chaîne
Chemin d'accès à une ressource dans une application ou une extension, exprimé par rapport à son répertoire d'installation.
Renvoie
-
chaîne
URL complète de la ressource.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
Si possible, ouvrez la page d'options de votre extension.
Le comportement précis peut dépendre de la clé [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
ou [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
de votre fichier manifeste, ou de la compatibilité de Chrome à ce moment-là. Par exemple, la page peut être ouverte dans un nouvel onglet, dans chrome://extensions, dans une application ou simplement sur une page d'options ouverte. La page appelante ne sera jamais actualisée.
Si votre extension ne déclare pas de page d'options ou si Chrome n'a pas réussi à en créer une pour une autre raison, le rappel définira lastError
.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
reload()
chrome.runtime.reload()
Recharge l'application ou l'extension. Cette méthode n'est pas compatible avec le mode Kiosque. Pour le mode Kiosque, utilisez la méthode chrome.runtime.restart().
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
Demande une vérification immédiate des mises à jour de cette application/extension.
Important: La plupart des extensions/applications ne doivent pas utiliser cette méthode, car Chrome effectue déjà des vérifications automatiques toutes les deux ou trois heures, et vous pouvez écouter l'événement runtime.onUpdateAvailable
sans avoir à appeler requestUpdateCheck.
Cette méthode ne peut être appelée que dans des circonstances très limitées, par exemple si votre extension communique avec un service de backend et que le service de backend a déterminé que la version de l'extension cliente est très obsolète et que vous souhaitez inviter un utilisateur à effectuer la mise à jour. La plupart des autres utilisations de requestUpdateCheck, telles que l'appel inconditionnel en fonction d'un minuteur répété, ne servent probablement qu'à gaspiller les ressources du client, du réseau et du serveur.
Remarque: En cas d'appel avec un rappel, au lieu de renvoyer un objet, cette fonction renvoie les deux propriétés sous forme d'arguments distincts transmis au rappel.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: object) => void
-
résultat
objet
Chrome 109 et versions ultérieuresL'objet RequestUpdateCheckResult contenant l'état de la recherche de mises à jour et tous les détails du résultat si une mise à jour est disponible
-
status
Résultat de la vérification des mises à jour.
-
version
string facultatif
Si une mise à jour est disponible, cet attribut contient la version de la mise à jour disponible.
-
-
Renvoie
-
Promise<object>
Chrome 109 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
restart()
chrome.runtime.restart()
Redémarrez l'appareil ChromeOS lorsque l'application s'exécute en mode Kiosque. Sinon, il s'agit d'une opération no-op.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Redémarrez l'appareil ChromeOS lorsque l'application s'exécute en mode Kiosque après le nombre de secondes définies. En cas de nouvel appel avant la fin de l'heure, le redémarrage sera retardé. S'il est appelé avec la valeur -1, le redémarrage est annulé. Il s'agit d'une opération no-op en mode non kiosque. Elle n'est autorisée à être appelée à plusieurs reprises que par la première extension pour appeler cette API.
Paramètres
-
secondes
Nombre
Délai d'attente en secondes avant de redémarrer l'appareil, ou -1 pour annuler un redémarrage planifié.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Envoie un message unique aux écouteurs d'événements de votre extension ou d'une autre extension/application. Semblable à runtime.connect
, mais n'envoie qu'un seul message, avec une réponse facultative. Si vous envoyez l'événement à votre extension, l'événement runtime.onMessage
est déclenché dans chaque frame de votre extension (à l'exception de celui de l'expéditeur) ou runtime.onMessageExternal
s'il s'agit d'une extension différente. Notez que cette méthode ne permet pas aux extensions d'envoyer des messages aux scripts de contenu. Pour envoyer des messages à des scripts de contenu, utilisez tabs.sendMessage
.
Paramètres
-
extensionId
string facultatif
ID de l'extension à laquelle envoyer le message. En cas d'omission, le message sera envoyé à votre propre extension/application. Obligatoire si vous envoyez des messages depuis une page Web pour la messagerie Web.
-
message
toutes
Message à envoyer. Ce message doit être un objet JSON.
-
options
objet facultatif
-
includeTlsChannelId
Booléen facultatif
Indique si l'ID du canal TLS est transmis à onMessageExternal pour les processus qui écoutent l'événement de connexion.
-
-
rappel
fonction facultative
Chrome 99 et versions ultérieuresLe paramètre
callback
se présente comme suit :(response: any) => void
-
réponse
toutes
Objet de réponse JSON envoyé par le gestionnaire du message. Si une erreur se produit lors de la connexion à l'extension, le rappel est appelé sans argument et
runtime.lastError
est défini sur le message d'erreur.
-
Renvoie
-
Promettre<tout>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Envoyez un seul message à une application native. Cette méthode nécessite l'autorisation "nativeMessaging"
.
Paramètres
-
application
chaîne
Nom de l'hôte de messagerie native.
-
message
objet
Message qui sera transmis à l'hôte de messagerie native.
-
rappel
fonction facultative
Chrome 99 et versions ultérieuresLe paramètre
callback
se présente comme suit :(response: any) => void
-
réponse
toutes
Message de réponse envoyé par l'hôte de messagerie native. Si une erreur se produit lors de la connexion à l'hôte de messagerie native, le rappel est appelé sans argument et
runtime.lastError
est défini sur le message d'erreur.
-
Renvoie
-
Promettre<tout>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
Définit l'URL à consulter lors de la désinstallation. Cela peut être utilisé pour nettoyer les données côté serveur, effectuer des analyses et mettre en œuvre des enquêtes. 1 023 caractères maximum.
Paramètres
-
url
chaîne
URL à ouvrir après la désinstallation de l'extension. Cette URL doit avoir un schéma http: ou https:. Définissez une chaîne vide pour ne pas ouvrir de nouvel onglet lors de la désinstallation.
-
rappel
fonction facultative
Chrome 45 ou version ultérieureLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 99 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
Événements
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Veuillez utiliser runtime.onRestartRequired
.
Se déclenche lorsqu'une mise à jour de Chrome est disponible, mais qui n'est pas installée immédiatement, car le navigateur doit être redémarré.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
Déclenché lorsqu'une connexion est établie à partir d'un processus d'extension ou d'un script de contenu (par runtime.connect
).
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(port: Port) => void
-
port
-
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
Déclenché lorsqu'une connexion est établie à partir d'une autre extension (par runtime.connect
) ou d'un site Web pouvant se connecter en externe.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(port: Port) => void
-
port
-
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Déclenché lorsqu'une connexion est établie à partir d'une application native. Cet événement nécessite l'autorisation "nativeMessaging"
. Elle n'est compatible qu'avec Chrome OS.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(port: Port) => void
-
port
-
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
Déclenché lors de la première installation de l'extension, de la mise à jour de l'extension ou de Chrome.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(details: object) => void
-
détails
objet
-
id
string facultatif
Indique l'ID de l'extension de module partagé importée qui a été mise à jour. Cette valeur n'est présente que si la valeur de "reason" est "shared_module_update".
-
previousVersion
string facultatif
Indique la version précédente de l'extension, qui vient d'être mise à jour. Cet attribut n'est présent que si la valeur de "reason" est "update".
-
reason
Motif de l'envoi de cet événement.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Déclenché lorsqu'un message est envoyé depuis un processus d'extension (par runtime.sendMessage
) ou un script de contenu (par tabs.sendMessage
).
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
toutes
-
expéditeur
-
sendResponse
function
Le paramètre
sendResponse
se présente comme suit :() => void
-
retours
Booléen | Non défini
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
Déclenché lorsqu'un message est envoyé depuis une autre extension (par runtime.sendMessage
). Ne peut pas être utilisé dans un script de contenu.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
toutes
-
expéditeur
-
sendResponse
function
Le paramètre
sendResponse
se présente comme suit :() => void
-
retours
Booléen | Non défini
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Déclenché lorsqu'une application ou l'appareil sur lequel elle s'exécute doivent être redémarrés L'application doit fermer toutes ses fenêtres dès que possible pour que le redémarrage ait lieu. Si l'application ne fait rien, le redémarrage sera imposé après un délai de grâce de 24 heures. Actuellement, cet événement n'est déclenché que pour les applications kiosque Chrome OS.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(reason: OnRestartRequiredReason) => void
-
reason
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Déclenché lorsqu'un profil sur lequel cette extension est installée démarre pour la première fois. Cet événement n'est pas déclenché lors du démarrage d'un profil de navigation privée, même si cette extension fonctionne en mode de navigation privée "split".
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
Envoyé sur la page de l'événement juste avant qu'il ne soit déchargé. Cela permet à l'extension de procéder à un nettoyage. Étant donné que la page est en cours de déchargement, il n'est pas garanti que les opérations asynchrones lancées lors de la gestion de cet événement se terminent. Si la page d'événement enregistre d'autres activités avant son déchargement, l'événement onSuspendCanceled sera envoyé et la page ne sera pas déchargée.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
Envoyé après onSuspend pour indiquer que l'application ne sera pas déchargée après tout.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
Déclenché lorsqu'une mise à jour est disponible, mais qui n'est pas installée immédiatement parce que l'application est en cours d'exécution. Si vous ne faites rien, la mise à jour sera installée lors du prochain déchargement de la page en arrière-plan. Si vous souhaitez qu'elle soit installée plus tôt, vous pouvez appeler explicitement chrome.runtime.reload(). Si votre extension utilise une page d'arrière-plan persistante, bien évidemment, cette dernière ne sera jamais déchargée. Par conséquent, sauf si vous appelez chrome.runtime.reload() manuellement en réponse à cet événement, la mise à jour ne sera installée qu'au prochain redémarrage de Chrome. Si aucun gestionnaire n'écoute cet événement et que votre extension dispose d'une page persistante en arrière-plan, elle se comporte comme si chrome.runtime.reload() était appelé en réponse à cet événement.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(details: object) => void
-
détails
objet
-
version
chaîne
Numéro de version de la mise à jour disponible.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Déclenché lorsqu'une connexion est établie à partir d'un script utilisateur de cette extension.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(port: Port) => void
-
port
-
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
Déclenché lorsqu'un message est envoyé à partir d'un script utilisateur associé à la même extension
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
toutes
-
expéditeur
-
sendResponse
function
Le paramètre
sendResponse
se présente comme suit :() => void
-
retours
Booléen | Non défini
-