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 des URL en URL complètes.
La plupart des membres de cette API ne nécessitent aucune autorisation. Cette autorisation est nécessaire pour connectNative()
, sendNativeMessage()
et onNativeConnect
.
L'exemple suivant montre comment déclarer l'autorisation "nativeMessaging"
dans le fichier manifeste:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Concepts et utilisation
L'API Runtime fournit des méthodes pour prendre en charge un certain nombre de domaines dans lesquels vos extensions peuvent utiliser:
- Transmission des messages
- Votre extension peut communiquer avec différents contextes au sein de votre extension, mais aussi avec d'autres extensions à l'aide des méthodes et événements suivants:
connect()
,onConnect
,onConnectExternal
sendMessage()
onMessage
etonMessageExternal
. De plus, votre extension peut transmettre des messages aux applications natives sur l'appareil de l'utilisateur en utilisantconnectNative()
etsendNativeMessage()
- Accéder aux métadonnées des extensions et des plates-formes
- Ces méthodes vous permettent de récupérer plusieurs métadonnées spécifiques concernant l'extension et la
Google Cloud. Les méthodes de cette catégorie sont les suivantes :
getManifest()
etgetPlatformInfo()
- Gérer le cycle de vie des extensions et leurs options
- Ces propriétés vous permettent d'effectuer certaines 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()
etsetUninstallURL()
. - Utilitaires d'aide
- Ces méthodes sont utiles, comme la conversion de représentations de ressources internes en
des formats externes. Les méthodes de cette catégorie sont les suivantes :
getURL()
- Utilitaires du mode Kiosque
- Ces méthodes ne sont disponibles que sur ChromeOS et servent principalement à implémenter des kiosques.
Les méthodes de cette catégorie sont les suivantes :
restart()
etrestartAfterDelay()
`.
Comportement des extensions non empaquetées
Lorsqu'une extension non empaquetée est rechargée, elle est traitée comme une mise à jour. Cela signifie que
L'événement chrome.runtime.onInstalled
se déclenchera avec le motif "update"
. Ce
inclut le moment où l'extension est rechargée avec chrome.runtime.reload()
.
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 les composants Extension
une page Web. Les deux différences sont que les éléments de l'extension doivent être présentés sous la forme d'éléments Web
des ressources accessibles et que les scripts de contenu sont généralement chargés d'injecter
composants d'extension.
Dans cet exemple, l'extension ajoute logo.png
à la page que le contenu
est injectée à l'aide de runtime.getURL()
pour créer un
URL complète. Mais d'abord, l'élément doit être déclaré en tant que ressource accessible sur le Web dans le fichier manifeste.
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 au service worker à partir d'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. À l'instar de 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. À la place, l'extension peut utiliser des messages transmettre pour coordonner ces différents contextes.
Dans cet exemple, le script de contenu a besoin de données provenant du service worker de l'extension pour
pour initialiser son UI. Pour obtenir ces données, il transmet le message get-user-data
défini par le développeur
au service worker. Celui-ci renvoie une copie des informations sur 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);
});
service-worker.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);
}
});
Recueillir des commentaires sur la désinstallation
De nombreuses extensions utilisent des enquêtes post-désinstallation pour comprendre comment elles pourraient mieux répondre 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
Consultez la démonstration Manifest V3 – Ressources accessibles sur le Web pour découvrir d'autres exemples d'API Runtime.
Types
ContextFilter
Filtre à mettre en 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
Énumération
"TAB"
Spécifie le type de contexte sous forme d'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 hébergeant le contenu des extensions.
Propriétés
-
ID de contexte
chaîne
Identifiant unique pour ce contexte
-
contextType
Type de contexte auquel cela correspond.
-
documentId
chaîne facultatif
UUID du document associé à ce contexte, ou non défini si ce contexte n'est pas hébergé dans un document.
-
documentOrigin
chaîne facultatif
Origine du document associée à ce contexte ou non définie si le contexte n'est pas hébergé dans un document.
-
documentUrl
chaîne facultatif
URL du document associé à ce contexte. Elle n'est pas définie si le contexte n'est pas hébergé dans un document.
-
frameId
Nombre
ID du frame pour ce contexte, ou -1 si le contexte n'est pas hébergé dans un frame.
-
navigation privée
booléen
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 le 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
chaîne facultatif
Chrome 106 et versions ultérieuresUn UUID du document qui a ouvert la connexion.
-
documentLifecycle
chaîne facultatif
Chrome 106 et versions ultérieuresCycle de vie dans lequel se trouve le 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
Le cadre qui a ouvert la connexion. 0 pour les cadres de niveau supérieur, et 0 pour les cadres enfants. Il ne sera défini que si
tab
est défini. -
id
chaîne facultatif
ID de l'extension qui a ouvert la connexion, le cas échéant.
-
nativeApplication
chaîne facultatif
Chrome 74 ou version ultérieureNom de l'application native qui a ouvert la connexion, le cas échéant.
-
origine
chaîne facultatif
Chrome 80 ou version ultérieureOrigine de la page ou du cadre qui a ouvert la connexion. Elle peut différer de la propriété d'URL (par exemple, about:blank) ou opaque (par exemple, iFrame en bac à sable). Cela permet de déterminer si l'origine peut être fiable si l'URL ne nous permet pas de la déterminer immédiatement.
-
tabulation
Tabulation facultatif
Le
tabs.Tab
qui a ouvert la connexion, le cas échéant. Cette propriété n'est présente que si la connexion a été ouverte à partir d'un onglet (y compris les scripts de contenu), et uniquement si le récepteur est une extension, et non une application. -
tlsChannelId
chaîne facultatif
ID du canal TLS de la page ou du frame qui a ouvert la connexion, si l'extension l'a demandé et si disponible.
-
url
chaîne facultatif
URL de la page ou du cadre qui a ouvert la connexion. Si l'expéditeur se trouve dans un iFrame, il s'agira de l'URL de l'iFrame, et non de l'URL de la page qui l'héberge.
OnInstalledReason
Raison pour laquelle cet événement est envoyé.
Énumération
"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
Raison pour laquelle l'événement est envoyé. "app_update" est utilisé lorsque le redémarrage est nécessaire en raison de la mise à jour de l'application vers une version plus récente. "os_update" est utilisé lorsque le redémarrage est nécessaire, car le navigateur ou le système d'exploitation est mis à jour vers une version plus récente. "periodic" est utilisé lorsque le système s'exécute pendant une durée supérieure au temps d'activité autorisé défini dans la règle d'entreprise.
Énumération
"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 en tant que redémarrage périodique de l'application.
PlatformArch
Architecture du processeur de la machine.
Énumération
"arm"
Spécifie l'architecture du processeur en tant que "arm".
"arm64"
Spécifie l'architecture de l'outil de traitement sous la forme arm64.
"x86-32"
Spécifie l'architecture du processus comme x86-32.
"x86-64"
Spécifie l'architecture de l'outil de traitement au format x86-64.
"mips"
Spécifie l'architecture du processus sous forme de mips.
"mips64"
Spécifie l'architecture du processus au format mips64.
PlatformInfo
Objet contenant des informations sur la plate-forme actuelle.
Propriétés
-
arc
Architecture du processeur de la machine.
-
nacl_arch
Architecture cliente native. Elle peut être différente de l'arche sur certaines plates-formes.
-
os
Système d'exploitation sur lequel Chrome est exécuté.
PlatformNaclArch
Architecture cliente native. Elle peut être différente de l'arche sur certaines plates-formes.
Énumération
"arm"
Spécifie l'architecture cliente native en tant que "arm".
"x86-32"
Spécifie l'architecture cliente native comme x86-32.
"x86-64"
Spécifie l'architecture cliente native comme x86-64.
"mips"
Spécifie l'architecture cliente native sous la forme de mips.
"mips64"
Spécifie l'architecture cliente native au format mips64.
PlatformOs
Système d'exploitation sur lequel Chrome est exécuté.
Énumération
"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"
Indique 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 permettant une communication bidirectionnelle avec d'autres pages. Pour en savoir plus, consultez la section Connexions de longue durée.
Propriétés
-
nom
chaîne
Nom du port, tel que spécifié dans l'appel de
runtime.connect
. -
onDisconnect
Événement<functionvoid>
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 une erreur. Si le port est fermé via la fonctionnalité de déconnexion, cet événement se déclenche uniquement à l'autre extrémité. Cet événement est déclenché au maximum une fois (voir également Durée de vie du port).La fonction
onDisconnect.addListener
se présente comme suit:(callback: function) => {...}
-
onMessage
Événement<functionvoid>
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 uniquement présente sur les ports transmis aux écouteurs onConnect / onConnectExternal / onConnectNative.
-
déconnecter
vide
Déconnectez immédiatement le port. Appeler
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
vide
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
tous
Chrome (version 52 ou ultérieure)Message à envoyer. Cet objet doit pouvoir être utilisé au format JSON.
-
RequestUpdateCheckStatus
Résultat de la vérification des mises à jour.
Énumération
"throttled"
Spécifie que la vérification de l'état a été limitée. Cela peut se produire après des vérifications répétées dans un court laps de temps.
"no_update"
Spécifie qu'aucune mise à jour n'est disponible à installer.
"update_available"
Spécifie qu'une mise à jour est disponible à installer.
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 d'API n'est pas défini pour les autres. Cela n'est défini que dans le cadre du rappel de cette fonction. Si une erreur est générée, mais que runtime.lastError
n'est pas accessible dans le rappel, un message est consigné dans la console. Il indique la fonction API qui a 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
chaîne 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 dans une extension (comme la page en arrière-plan) ou d'autres extensions/applications. Cela est utile pour les scripts de contenu qui se connectent à leurs processus d'extension, la communication entre les applications et les extensions, et la messagerie Web. Notez que cette méthode ne se connecte à aucun paramètre "Listener" dans un script de contenu. Les extensions peuvent se connecter à des scripts de contenu intégrés dans des onglets via tabs.connect
.
Paramètres
-
extensionId
chaîne facultatif
ID de l'extension à laquelle se connecter. En cas d'omission, une tentative de connexion sera effectuée avec votre propre extension. Obligatoire si vous envoyez des messages depuis une page Web pour la messagerie Web.
-
connectInfo
objet facultatif
-
includeTlsChannelId
Booléen facultatif
Indique si l'ID de la chaîne TLS sera transmis à onConnectExternal pour les processus qui écoutent l'événement de connexion.
-
nom
chaîne 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 Messagerie native.
Paramètres
-
application
chaîne
Nom de l'application enregistrée à laquelle se connecter.
Renvoie
-
Port via lequel les messages peuvent être envoyés et reçus avec l'application
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Récupère la fenêtre JavaScript "window". pour 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. Si aucune page n'est affichée en arrière-plan, une erreur est définie.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(backgroundPage?: Window) => void
-
backgroundPage
Fenêtre facultatif
La "fenêtre" JavaScript pour la page d'arrière-plan.
-
Renvoie
-
Promise<Window | indéfini>
Chrome 99 ou version ultérieureLes 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.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Extrait des informations sur les contextes actifs associés à cette extension
Paramètres
-
filtre
Filtre permettant de trouver les contextes correspondants. Un contexte correspond s'il correspond à tous les champs spécifiés dans le filtre. Tout champ non spécifié dans le filtre correspond à tous les contextes.
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(contexts: ExtensionContext[]) => void
-
contexts
Les contextes correspondants, le cas échéant.
-
Renvoie
-
Promise<ExtensionContext[]>
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.
getManifest()
chrome.runtime.getManifest()
Affiche des détails 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 du package.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Renvoie
-
Promise<DirectoryEntry>
Chrome 122 ou version ultérieureLes 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.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Affiche des informations sur la plate-forme actuelle.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Renvoie
-
Promise<PlatformInfo>
Chrome 99 ou version ultérieureLes 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.
getURL()
chrome.runtime.getURL(
path: string,
)
Convertit en URL complète un chemin d'accès relatif contenu dans un répertoire d'installation d'application ou d'extension.
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 ce que Chrome prend en charge à 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. Cela n'entraînera jamais l'actualisation de la page de l'appelant.
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
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promesse<void>
Chrome 99 ou version ultérieureLes 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.
reload()
chrome.runtime.reload()
Actualise l'application ou l'extension. Cette méthode n'est pas disponible en 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 ou de cette 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. Vous pouvez donc é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 client est très obsolète et que vous souhaitez inviter un utilisateur à effectuer une mise à jour. La plupart des autres utilisations de requestUpdateCheck, comme l'appel sans condition en fonction d'un minuteur répété, ne servent probablement qu'à gaspiller des ressources client, réseau et serveur.
Remarque: Lorsqu'elle est appelée avec un rappel, cette fonction renvoie les deux propriétés sous la forme d'arguments distincts transmis au rappel au lieu de renvoyer un objet.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(result: object) => void
-
résultat
objet
Chrome 109 et versions ultérieuresObjet RequestUpdateCheckResult qui contient l'état de la vérification des mises à jour et tous les détails du résultat si une mise à jour est disponible
-
Résultat de la vérification des mises à jour.
-
version
chaîne 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 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.
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 au bout de quelques secondes. Si vous êtes rappelé avant la fin du délai, le redémarrage sera retardé. S'il est appelé avec une valeur de -1, le redémarrage est annulé. Il s'agit d'une opération no-op en mode hors kiosque. Elle ne peut être appelée à plusieurs reprises que par la première extension qui appelle 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
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promesse<void>
Chrome 99 ou version ultérieureLes 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.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Envoie un seul message aux écouteurs d'événements au sein 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
sera déclenché dans chaque frame de votre extension (sauf celle de l'expéditeur) ou runtime.onMessageExternal
s'il s'agit d'une autre extension. Notez que les extensions ne peuvent pas envoyer de messages à des scripts de contenu avec cette méthode. Pour envoyer des messages à des scripts de contenu, utilisez tabs.sendMessage
.
Paramètres
-
extensionId
chaîne facultatif
ID de l'extension à laquelle envoyer le message. S'il est omis, le message sera envoyé à votre propre extension/application. Obligatoire si vous envoyez des messages depuis une page Web pour la messagerie Web.
-
message
tous
Message à envoyer. Ce message doit être un objet JSON pouvant être appliqué.
-
options
objet facultatif
-
includeTlsChannelId
Booléen facultatif
Indique si l'ID de la chaîne TLS sera transmis à onMessageExternal pour les processus qui écoutent l'événement de connexion.
-
-
rappel
function facultatif
Chrome 99 ou version ultérieureLe paramètre
callback
se présente comme suit:(response: any) => void
-
réponse
tous
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
-
Promesse<tous>
Chrome 99 ou version ultérieureLes 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.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Envoyer 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 transmis à l'hôte de messagerie native.
-
rappel
function facultatif
Chrome 99 ou version ultérieureLe paramètre
callback
se présente comme suit:(response: any) => void
-
réponse
tous
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
-
Promesse<tous>
Chrome 99 ou version ultérieureLes 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.
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
function facultatif
Chrome 45 ou version ultérieureLe paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promesse<void>
Chrome 99 ou version ultérieureLes 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.
Événements
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Veuillez utiliser runtime.onRestartRequired
.
Déclenché lorsqu'une mise à jour de Chrome est disponible, mais n'est pas installée immédiatement, car un redémarrage du navigateur est nécessaire.
Paramètres
-
rappel
fonction
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
fonction
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 être connecté en externe.
Paramètres
-
rappel
fonction
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"
. Il n'est compatible qu'avec Chrome OS.
Paramètres
-
rappel
fonction
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 et de la mise à jour de Chrome.
Paramètres
-
rappel
fonction
Le paramètre
callback
se présente comme suit:(details: object) => void
-
détails
objet
-
id
chaîne facultatif
Indique l'ID de l'extension de module partagé importée qui a été mise à jour. Ce champ n'est présent que si "reason" correspond à "shared_module_update".
-
previousVersion
chaîne facultatif
Indique la version précédente de l'extension, qui vient d'être mise à jour. Ce champ n'est présent que si "reason" est "update" (mise à jour).
-
reason
Raison pour laquelle cet événement est envoyé.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Déclenché lorsqu'un message est envoyé à partir d'un processus d'extension (par runtime.sendMessage
) ou d'un script de contenu (par tabs.sendMessage
).
Paramètres
-
rappel
fonction
Le paramètre
callback
se présente comme suit:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
tous
-
expéditeur
-
sendResponse
fonction
Le paramètre
sendResponse
se présente comme suit:() => void
-
retours
boolean | indéfinie
-
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ée dans un script de contenu.
Paramètres
-
rappel
fonction
Le paramètre
callback
se présente comme suit:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
tous
-
expéditeur
-
sendResponse
fonction
Le paramètre
sendResponse
se présente comme suit:() => void
-
retours
boolean | indéfinie
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Déclenché lorsqu'une application ou l'appareil sur lequel elle s'exécute doit être redémarré. L'application doit fermer toutes ses fenêtres au plus tôt pour permettre le redémarrage. Si l'application ne fait rien, l'application redémarre 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
fonction
Le paramètre
callback
se présente comme suit:(reason: OnRestartRequiredReason) => void
-
reason
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Déclenché au démarrage d'un profil dans lequel cette extension est installée pour la première fois. Cet événement n'est pas déclenché au démarrage d'un profil de navigation privée, même si cette extension fonctionne en mode fractionné le mode navigation privée.
Paramètres
-
rappel
fonction
Le paramètre
callback
se présente comme suit:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
Envoyé à la page de l'événement juste avant son déchargement. Cela permet à l'extension d'effectuer un nettoyage. Étant donné que le déchargement de la page est en cours, il n'est pas garanti que les opérations asynchrones lancées lors du traitement de cet événement se terminent. Si l'activité de la page d'événement se poursuit avant son déchargement, l'événement onSuspendCanceled est envoyé et la page n'est pas déchargée.
Paramètres
-
rappel
fonction
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
fonction
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 n'est pas installée immédiatement, car l'application est en cours d'exécution. Sans action de votre part, 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 persistante en arrière-plan, celle-ci n'est évidemment 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 possède une page d'arrière-plan persistante, elle se comporte comme si chrome.runtime.reload() était appelé en réponse à cet événement.
Paramètres
-
rappel
fonction
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 à partir de cette extension.
Paramètres
-
rappel
fonction
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
fonction
Le paramètre
callback
se présente comme suit:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
message
tous
-
expéditeur
-
sendResponse
fonction
Le paramètre
sendResponse
se présente comme suit:() => void
-
retours
boolean | indéfinie
-