Descrizione
Utilizza l'API chrome.runtime
per recuperare il service worker, restituire i dettagli del manifest e ascoltare gli eventi e rispondere durante il ciclo di vita dell'estensione. Puoi utilizzare questa API anche per convertire il percorso relativo degli URL in URL completi.
Panoramica
L'API Runtime fornisce metodi per supportare una serie di aree di funzionalità che le estensioni possono utilizzare:
- Trasmissione messaggio
- L'estensione può comunicare con diversi contesti all'interno dell'estensione e anche con altre estensioni utilizzando i seguenti metodi ed eventi: connect(), onConnect, onConnectExternal, sendMessage(), onMessage e onMessageExternal. Inoltre, l'estensione può trasmettere messaggi alle applicazioni native sul dispositivo dell'utente utilizzando connectNative() e sendNativeMessage().
- Accesso ai metadati di estensioni e piattaforme
- Questi metodi ti consentono di recuperare diversi metadati specifici relativi all'estensione e alla piattaforma. I metodi in questa categoria includono getManifest() e getPlatformInfo().
- Gestione del ciclo di vita e delle opzioni delle estensioni
- Queste proprietà ti consentono di eseguire alcune meta-operazioni sull'estensione e visualizzare la pagina delle opzioni. I metodi e gli eventi di questa categoria includono onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() e setDisinstallaURL().
- Utilità di supporto
- Questi metodi offrono utilità come la conversione delle rappresentazioni interne delle risorse in formati esterni. I metodi in questa categoria includono getURL().
- Utilità della modalità kiosk
- Questi metodi sono disponibili solo su ChromeOS ed esistono principalmente per supportare le implementazioni dei kiosk. I metodi in questa categoria includono restart e restartAfterDelay.
Autorizzazioni
La maggior parte dei metodi sull'API Runtime non richiede alcuna autorizzazione, ad eccezione di
sendNativeMessage e connectNative, che
richiedono l'autorizzazione nativeMessaging
.
Manifest
L'esempio seguente mostra come dichiarare l'autorizzazione nativeMessaging
nel manifest:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Casi d'uso
Aggiungere un'immagine a una pagina web
Affinché una pagina web possa accedere a un asset ospitato su un altro dominio, è necessario specificare l'URL completo della risorsa (ad es. <img src="https://example.com/logo.png">
). Lo stesso vale per l'inclusione di un asset di estensione su una pagina web. Le due differenze sono che gli asset dell'estensione devono essere esposti come risorse accessibili sul web e che in genere gli script dei contenuti sono responsabili dell'inserimento delle risorse delle estensioni.
In questo esempio, l'estensione aggiungerà logo.png
alla pagina in cui viene iniettato lo script dei contenuti utilizzando runtime.getURL()
per creare un URL completo. Prima però, l'asset deve essere dichiarato come risorsa accessibile dal web nel manifest.
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);
}
Invia dati dal service worker a uno script di contenuti
È comune che gli script di contenuti di un'estensione richiedano dati gestiti da un'altra parte dell'estensione, ad esempio il service worker. Proprio come due finestre del browser aperte sulla stessa pagina web, questi due contesti non possono accedere direttamente ai valori degli altri. L'estensione può utilizzare invece la trasmissione di messaggi per coordinarsi tra questi diversi contesti.
In questo esempio, lo script dei contenuti richiede alcuni dati dal service worker dell'estensione per inizializzare la sua UI. Per ottenere questi dati, passa un messaggio get-user-data
al service worker e
risponde con una copia delle informazioni dell'utente.
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);
}
});
Raccogli feedback sulla disinstallazione
Molte estensioni utilizzano i sondaggi successivi alla disinstallazione per capire in che modo l'estensione potrebbe servire meglio gli utenti e migliorare la fidelizzazione. L'esempio seguente mostra come aggiungere questa funzionalità.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
Esempi di estensioni
Per altri esempi di API Runtime, consulta la demo delle risorse accessibili al web (Manifest V3).
Tipi
ContextFilter
Un filtro per la corrispondenza con determinati contesti di estensioni. I contesti corrispondenti devono corrispondere a tutti i filtri specificati; qualsiasi filtro non specificato corrisponde a tutti i contesti disponibili. In questo modo, un filtro "{}" corrisponderà a tutti i contesti disponibili.
Proprietà
-
contextIds
string[] facoltativo
-
contextTypes
ContextType[] facoltativo
-
documentIds
string[] facoltativo
-
documentOrigins
string[] facoltativo
-
documentUrls
string[] facoltativo
-
frameIds
number[] facoltativo
-
in incognito
booleano facoltativo
-
tabIds
number[] facoltativo
-
windowIds
number[] facoltativo
ContextType
Enum
"TAB"
Specifica il tipo di contesto come scheda
"POPUP"
Specifica il tipo di contesto come finestra popup dell'estensione
"BACKGROUND"
Specifica il tipo di contesto come service worker.
"OFFSCREEN_DOCUMENT"
Specifica il tipo di contesto come documento fuori schermo.
"SIDE_PANEL"
Specifica il tipo di contesto come riquadro laterale.
ExtensionContext
Un contesto che ospita contenuti di estensione.
Proprietà
-
contextId
stringa
Un identificatore univoco per questo contesto
-
contextType
Il tipo di contesto a cui corrisponde.
-
documentId
stringa facoltativo
Un UUID per il documento associato a questo contesto o non definito se questo contesto è ospitato non in un documento.
-
documentOrigin
stringa facoltativo
L'origine del documento associato a questo contesto o non definita se il contesto non è ospitato in un documento.
-
documentUrl
stringa facoltativo
L'URL del documento associato a questo contesto o non definito se il contesto non è ospitato in un documento.
-
frameId
numero
L'ID del frame per questo contesto o -1 se questo contesto non è ospitato in un frame.
-
in incognito
boolean
Se il contesto è associato a un profilo di navigazione in incognito.
-
tabId
numero
L'ID della scheda per questo contesto o -1 se questo contesto non è ospitato in una scheda.
-
windowId
numero
L'ID della finestra per questo contesto o -1 se questo contesto non è ospitato in una finestra.
MessageSender
Un oggetto contenente informazioni sul contesto dello script che ha inviato un messaggio o una richiesta.
Proprietà
-
documentId
stringa facoltativo
Chrome 106 e versioni successiveL'UUID del documento che ha aperto la connessione.
-
documentLifecycle
stringa facoltativo
Chrome 106 e versioni successiveIl ciclo di vita del documento che ha aperto la connessione al momento della creazione della porta. Tieni presente che lo stato del ciclo di vita del documento potrebbe essere cambiato dalla creazione delle porte.
-
frameId
numero facoltativo
Il frame che ha aperto la connessione. 0 per i frame di primo livello, positivo per i frame secondari. Verrà impostato solo quando viene impostato
tab
. -
id
stringa facoltativo
L'ID dell'estensione che ha aperto la connessione, se presente.
-
nativeApplication
stringa facoltativo
Chrome 74 e versioni successiveIl nome dell'applicazione nativa che ha aperto la connessione, se presente.
-
origine
stringa facoltativo
Chrome 80 e versioni successiveL'origine della pagina o del frame che ha aperto la connessione. Può variare dalla proprietà dell'URL (ad es. about:blank) o essere opaco (ad es. iframe con sandbox). Questo è utile per identificare se l'origine è attendibile se non riusciamo a distinguerla immediatamente dall'URL.
-
Home
Scheda facoltativa
L'elemento
tabs.Tab
che ha aperto la connessione, se presente. Questa proprietà sarà presente solo quando la connessione è stata aperta da una scheda (inclusi gli script di contenuti) e solo se il destinatario è un'estensione, non un'app. -
tlsChannelId
stringa facoltativo
L'ID canale TLS della pagina o del frame che ha aperto la connessione, se richiesto dall'estensione e se disponibile.
-
url
stringa facoltativo
L'URL della pagina o del frame che ha aperto la connessione. Se il mittente si trova in un iframe, sarà l'URL dell'iframe e non l'URL della pagina che lo ospita.
OnInstalledReason
Il motivo per cui l'evento è in fase di invio.
Enum
"install"
Specifica il motivo dell'evento come installazione.
"update"
Specifica il motivo dell'evento come aggiornamento dell'estensione.
"chrome_update"
Specifica il motivo dell'evento come aggiornamento di Chrome.
"shared_module_update"
Specifica il motivo dell'evento come aggiornamento di un modulo condiviso.
OnRestartRequiredReason
Il motivo per cui l'evento è stato inviato. "app_update" viene utilizzato quando è necessario riavviare perché l'applicazione è aggiornata a una versione più recente. "os_update" viene utilizzato quando è necessario eseguire il riavvio perché il browser/sistema operativo è aggiornato a una versione più recente. "periodico" viene utilizzato quando il sistema è in esecuzione per un tempo di attività superiore a quello consentito impostato nei criteri aziendali.
Enum
"app_update"
Specifica il motivo dell'evento come aggiornamento dell'app.
"os_update"
Specifica il motivo dell'evento come aggiornamento del sistema operativo.
"periodic"
Specifica il motivo dell'evento come un riavvio periodico dell'app.
PlatformArch
L'architettura del processore della macchina.
Enum
"arm"
Specifica l'architettura del processore come gruppo.
"arm64"
Specifica l'architettura del processore come arm64.
"x86-32"
Specifica l'architettura del processore come x86-32.
"x86-64"
Specifica l'architettura del processore come x86-64.
"mips"
Specifica l'architettura del processore come mips.
"mips64"
Specifica l'architettura del processore come mips64.
PlatformInfo
Un oggetto contenente informazioni sulla piattaforma corrente.
Proprietà
-
arco
L'architettura del processore della macchina.
-
nacl_arch
L'architettura client nativa. Questa impostazione potrebbe essere diversa da arch su alcune piattaforme.
-
os
Il sistema operativo su cui è in esecuzione Chrome.
PlatformNaclArch
L'architettura client nativa. Questa impostazione potrebbe essere diversa da arch su alcune piattaforme.
Enum
"arm"
Specifica l'architettura client nativa come gruppo.
"x86-32"
Specifica l'architettura client nativa come x86-32.
"x86-64"
Specifica l'architettura client nativa come x86-64.
"mips"
Specifica l'architettura client nativa come mips.
"mips64"
Specifica l'architettura client nativa come mips64.
PlatformOs
Il sistema operativo su cui è in esecuzione Chrome.
Enum
"mac"
Specifica il sistema operativo MacOS.
"win"
Specifica il sistema operativo Windows.
"android"
Specifica il sistema operativo Android.
"cros"
Specifica il sistema operativo Chrome.
"linux"
Specifica il sistema operativo Linux.
"openbsd"
Specifica il sistema operativo OpenBSD.
"fuchsia"
Specifica il sistema operativo Fuchsia.
Port
Oggetto che consente la comunicazione bidirezionale con altre pagine. Per saperne di più, consulta Connessioni di lunga durata.
Proprietà
-
nome
stringa
Il nome della porta, come specificato nella chiamata a
runtime.connect
. -
onDisconnect
Evento<functionvoidvoid>
Viene attivato quando la porta è disconnessa dalle altre estremità. Se la porta è stata disconnessa a causa di un errore, è possibile impostare
runtime.lastError
. Se la porta viene chiusa tramite disconnect, questo evento viene attivato solo dall'altra parte. Questo evento viene attivato al massimo una volta (vedi anche Durata della porta).La funzione
onDisconnect.addListener
ha il seguente aspetto:(callback: function) => {...}
-
onMessage
Evento<functionvoidvoid>
Questo evento viene attivato quando postMessage viene chiamato dall'altra estremità della porta.
La funzione
onMessage.addListener
ha il seguente aspetto:(callback: function) => {...}
-
mittente
MessageSender facoltativo
Questa proprietà sarà presente solo sulle porte passate ai listener onConnect / onConnectExternal / onConnectNative.
-
disconnetti
void
Scollega immediatamente la porta. La chiamata a
disconnect()
su una porta già disconnessa non ha alcun effetto. Quando una porta viene disconnessa, non verranno inviati nuovi eventi a questa porta.La funzione
disconnect
ha il seguente aspetto:() => {...}
-
postMessage
void
Invia un messaggio all'altra estremità della porta. Se la porta è disconnessa, viene visualizzato un errore.
La funzione
postMessage
ha il seguente aspetto:(message: any) => {...}
-
messaggio
Qualsiasi
Chrome 52 e versioni successiveIl messaggio da inviare. Questo oggetto deve essere compatibile in formato JSON.
-
RequestUpdateCheckStatus
Risultato del controllo degli aggiornamenti.
Enum
"throttled"
Specifica che il controllo dello stato è stato limitato. Questo può accadere dopo controlli ripetuti in un breve lasso di tempo.
"no_update"
Specifica che non sono disponibili aggiornamenti da installare.
"update_available"
Specifica che è disponibile un aggiornamento da installare.
Proprietà
id
L'ID dell'estensione/app.
Tipo
stringa
lastError
Compilato con un messaggio di errore se la chiamata di una funzione API ha esito negativo; altrimenti non è definita. Questo viene definito solo nell'ambito del callback di quella funzione. Se viene generato un errore, ma non è possibile accedere a runtime.lastError
all'interno del callback, nella console viene registrato un messaggio con l'elenco della funzione API che ha generato l'errore. Le funzioni API che restituiscono promesse non impostano questa proprietà.
Tipo
oggetto
Proprietà
-
messaggio
stringa facoltativo
Dettagli relativi all'errore che si è verificato.
Metodi
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
Tenta di connettere i listener all'interno di un'estensione (ad esempio la pagina in background) o di altre estensioni/app. È utile per gli script di contenuti che si connettono ai relativi processi di estensione, alle comunicazioni tra app/estensioni e ai messaggi web. Tieni presente che non si connette ad alcun listener in uno script di contenuti. Le estensioni possono connettersi a script di contenuti incorporati nelle schede tramite tabs.connect
.
Parametri
-
extensionId
stringa facoltativo
L'ID dell'estensione a cui connettersi. Se omesso, verrà effettuato un tentativo di connessione con la tua estensione. Obbligatorio se invii messaggi da una pagina web per la messaggistica web.
-
connectInfo
oggetto facoltativo
-
includeTlsChannelId
booleano facoltativo
Indica se l'ID canale TLS verrà trasmesso a onConnectExternal per i processi in ascolto dell'evento di connessione.
-
nome
stringa facoltativo
Verrà trasferito a onConnect per i processi in ascolto dell'evento di connessione.
-
Ritorni
-
Porta attraverso la quale i messaggi possono essere inviati e ricevuti. L'evento onDisconnect della porta viene attivato se l'estensione non esiste.
connectNative()
chrome.runtime.connectNative(
application: string,
)
Si connette a un'applicazione nativa nella macchina host. Questo metodo richiede l'autorizzazione "nativeMessaging"
. Per ulteriori informazioni, vedi native Messaging.
Parametri
-
applicazione
stringa
Il nome dell'applicazione registrata a cui connettersi.
Ritorni
-
Porta attraverso la quale i messaggi possono essere inviati e ricevuti con l'applicazione
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Recupera l'oggetto JavaScript "window" per la pagina in background in esecuzione all'interno dell'estensione/app corrente. Se la pagina di background è una pagina di eventi, il sistema verificherà che venga caricata prima di chiamare il callback. Se non esiste una pagina in background, viene impostato un errore.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(backgroundPage?: Window) => void
-
backgroundPage
Finestra facoltativa
L'oggetto JavaScript "window" per la pagina di sfondo.
-
Ritorni
-
Promise<Window | undefined>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Recupera informazioni sui contesti attivi associati a questa estensione
Parametri
-
filtra
Un filtro per trovare i contesti corrispondenti. Un contesto corrisponde se corrisponde a tutti i campi specificati nel filtro. Qualsiasi campo non specificato nel filtro corrisponde a tutti i contesti.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(contexts: ExtensionContext[]) => void
-
contesti
Gli eventuali contesti di corrispondenza.
-
Ritorni
-
Promise<ExtensionContext[]>
Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getManifest()
chrome.runtime.getManifest()
Restituisce i dettagli sull'app o sull'estensione dal file manifest. L'oggetto restituito è una serializzazione dell'intero file manifest.
Ritorni
-
oggetto
I dettagli del file manifest.
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
Restituisce una DirectoryEntry per la directory del pacchetto.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Ritorni
-
Promise<DirectoryEntry>
Chrome 122 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Restituisce informazioni sulla piattaforma corrente.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Ritorni
-
Promise<PlatformInfo>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getURL()
chrome.runtime.getURL(
path: string,
)
Converte un percorso relativo all'interno di una directory di installazione di app/estensioni in un URL completo.
Parametri
-
percorso
stringa
Percorso di una risorsa all'interno di un'app/estensione espresso in relazione alla relativa directory di installazione.
Ritorni
-
stringa
L'URL completo della risorsa.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
Se possibile, apri la pagina delle opzioni dell'estensione.
Il comportamento preciso potrebbe dipendere dalla chiave [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
o [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
del file manifest o dalle funzionalità supportate da Chrome in quel momento. Ad esempio, la pagina potrebbe essere aperta in una nuova scheda, all'interno di chrome://extensions, all'interno di un'app oppure potrebbe impostare lo stato attivo su una pagina di opzioni aperta. Non causerà mai il ricaricamento della pagina del chiamante.
Se l'estensione non dichiara una pagina di opzioni o se Chrome non è riuscito a crearne una per altri motivi, il callback verrà impostato lastError
.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
reload()
chrome.runtime.reload()
Ricarica l'app o l'estensione. Questo metodo non è supportato in modalità kiosk. Per la modalità kiosk, utilizza il metodo chrome.runtime.restart().
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
Richiede un controllo immediato degli aggiornamenti per questa app/estensione.
Importante: la maggior parte delle estensioni e delle app non dovrebbe utilizzare questo metodo, poiché Chrome esegue già controlli automatici a intervalli di alcune ore e puoi ascoltare l'evento runtime.onUpdateAvailable
senza dover chiamare requestUpdateCheck.
Questo metodo è appropriato per effettuare chiamate solo in circostanze molto limitate, ad esempio se l'estensione comunica con un servizio di backend e quest'ultimo ha stabilito che la versione dell'estensione client è molto obsoleta e vuoi richiedere a un utente di eseguire l'aggiornamento. La maggior parte degli altri utilizzi di requestUpdateCheck, come la chiamata incondizionata basata su un timer ripetuto, probabilmente serve solo a sprecare risorse del client, della rete e del server.
Nota: quando viene richiamata con un callback, invece di restituire un oggetto questa funzione restituisce le due proprietà come argomenti separati passati al callback.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: object) => void
-
risultato
oggetto
Chrome 109 e versioni successiveOggetto RequestUpdateCheckResult che contiene lo stato del controllo degli aggiornamenti ed eventuali dettagli del risultato se è disponibile un aggiornamento
-
status
Risultato del controllo degli aggiornamenti.
-
versione
stringa facoltativo
Se è disponibile un aggiornamento, questo contiene la versione dell'aggiornamento disponibile.
-
-
Ritorni
-
Promise<object>
Chrome 109 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
restart()
chrome.runtime.restart()
Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk. Altrimenti, è no-op.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk dopo i secondi indicati. Se chiamato di nuovo prima del termine del periodo di tempo, il riavvio subirà un ritardo. Se chiamato con il valore -1, il riavvio verrà annullato. È no-op in modalità non kiosk. È possibile chiamare ripetutamente solo la prima estensione per richiamare questa API.
Parametri
-
secondi
numero
Tempo di attesa in secondi prima di riavviare il dispositivo o -1 per annullare un riavvio programmato.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Invia un singolo messaggio ai listener di eventi all'interno della tua estensione o a un'estensione/app diversa. È simile a runtime.connect
, ma invia un solo messaggio con una risposta facoltativa. Se invii all'estensione, l'evento runtime.onMessage
viene attivato in ogni frame dell'estensione (ad eccezione del frame del mittente) o runtime.onMessageExternal
, se si tratta di un'estensione diversa. Tieni presente che le estensioni non possono inviare messaggi a script di contenuti utilizzando questo metodo. Per inviare messaggi a script di contenuti, utilizza tabs.sendMessage
.
Parametri
-
extensionId
stringa facoltativo
L'ID dell'estensione a cui inviare il messaggio. Se omesso, il messaggio verrà inviato alla tua estensione/app. Obbligatorio se invii messaggi da una pagina web per i messaggi web.
-
messaggio
Qualsiasi
Il messaggio da inviare. Questo messaggio deve essere un oggetto JSON compatibile.
-
opzioni del modello.
oggetto facoltativo
-
includeTlsChannelId
booleano facoltativo
Indica se l'ID canale TLS verrà trasmesso a onMessageExternal per i processi in ascolto dell'evento di connessione.
-
-
callback
funzione facoltativa
Chrome 99 e versioni successiveIl parametro
callback
ha il seguente aspetto:(response: any) => void
-
risposta
Qualsiasi
L'oggetto di risposta JSON inviato dal gestore del messaggio. Se si verifica un errore durante la connessione all'estensione, verrà chiamato il callback senza argomenti e
runtime.lastError
verrà impostato sul messaggio di errore.
-
Ritorni
-
Promessa<qualsiasi>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Inviare un singolo messaggio a un'applicazione nativa. Questo metodo richiede l'autorizzazione "nativeMessaging"
.
Parametri
-
applicazione
stringa
Il nome dell'host di messaggistica nativa.
-
messaggio
oggetto
Il messaggio che verrà passato all'host di messaggistica nativa.
-
callback
funzione facoltativa
Chrome 99 e versioni successiveIl parametro
callback
ha il seguente aspetto:(response: any) => void
-
risposta
Qualsiasi
Il messaggio di risposta inviato dall'host di messaggistica nativa. Se si verifica un errore durante la connessione all'host di messaggistica nativo, il callback verrà chiamato senza argomenti e
runtime.lastError
verrà impostato sul messaggio di errore.
-
Ritorni
-
Promessa<qualsiasi>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
Imposta l'URL da visitare al momento della disinstallazione. Queste informazioni possono essere utilizzate per ripulire i dati lato server, eseguire analisi e implementare sondaggi. Massimo 1023 caratteri.
Parametri
-
url
stringa
URL da aprire dopo la disinstallazione dell'estensione. L'URL deve avere uno schema http: o https:. Imposta una stringa vuota per non aprire una nuova scheda al momento della disinstallazione.
-
callback
funzione facoltativa
Chrome 45 e versioni successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
Eventi
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Utilizza runtime.onRestartRequired
.
Viene attivato quando è disponibile un aggiornamento di Chrome, ma non viene installato immediatamente perché è necessario il riavvio del browser.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
Attivato quando viene stabilita una connessione da un processo di estensione o da uno script di contenuti (da runtime.connect
).
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(port: Port) => void
-
porta
-
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
Attivato quando viene stabilita una connessione da un'altra estensione (da runtime.connect
) o da un sito web collegabile esternamente.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(port: Port) => void
-
porta
-
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Attivato quando viene stabilita una connessione da un'applicazione nativa. Questo evento richiede l'autorizzazione "nativeMessaging"
. È supportato solo su ChromeOS.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(port: Port) => void
-
porta
-
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
Si attiva alla prima installazione dell'estensione, all'aggiornamento dell'estensione a una nuova versione e all'aggiornamento di Chrome a una nuova versione.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
id
stringa facoltativo
Indica l'ID dell'estensione modulo condivisa importata che è stata aggiornata. Questo valore è presente solo se "motivo" è "shared_module_update".
-
previousVersion
stringa facoltativo
Indica la versione precedente dell'estensione, che è appena stata aggiornata. Questa opzione è presente solo se "motivo" è "aggiornamento".
-
motivo
Il motivo per cui l'evento è in fase di invio.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Si attiva quando un messaggio viene inviato da un processo di estensione (da runtime.sendMessage
) o da uno script di contenuti (da tabs.sendMessage
).
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
messaggio
Qualsiasi
-
mittente
-
sendResponse
funzione
Il parametro
sendResponse
ha il seguente aspetto:() => void
-
returns
booleano | non definito
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
Si attiva quando un messaggio viene inviato da un'altra estensione (da runtime.sendMessage
). Non può essere utilizzato in uno script di contenuti.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
messaggio
Qualsiasi
-
mittente
-
sendResponse
funzione
Il parametro
sendResponse
ha il seguente aspetto:() => void
-
returns
booleano | non definito
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Attivato quando un'app o il dispositivo su cui viene eseguita deve essere riavviato. L'app dovrebbe chiudere tutte le finestre il prima possibile per consentire il riavvio. Se l'app non esegue alcuna azione, una volta trascorso un periodo di tolleranza di 24 ore verrà eseguito un riavvio. Al momento, questo evento viene attivato solo per le app kiosk di ChromeOS.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(reason: OnRestartRequiredReason) => void
-
motivo
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Attivato quando un profilo in cui è installata l'estensione viene avviato per la prima volta. Questo evento non viene attivato quando viene avviato un profilo di navigazione in incognito, anche se l'estensione opera in modalità di navigazione in incognito "divisa".
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
Inviato alla pagina dell'evento appena prima dell'unload. In questo modo, l'estensione ha l'opportunità di eseguire qualche pulizia. Tieni presente che, poiché la pagina è in fase di unload, non è garantito che vengano completate eventuali operazioni asincrone avviate durante la gestione di questo evento. Se si verificano più attività per la pagina dell'evento prima che venga eseguito l'unload, verrà inviato l'evento onSospendiCanceled e la pagina non verrà scaricata.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
Inviata dopo onSospendi per indicare che, in fondo, l'app non verrà scaricata.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
Viene attivato quando è disponibile un aggiornamento, ma non viene installato immediatamente perché l'app è attualmente in esecuzione. Se non fai nulla, l'aggiornamento verrà installato la volta successiva che la pagina in background viene scaricata. Se vuoi che venga installata prima, puoi chiamare esplicitamente chrome.runtime.reload(). Se l'estensione utilizza una pagina in background permanente, ovviamente la pagina di sfondo non viene mai scaricata. Pertanto, a meno che non chiami manualmente chrome.runtime.reload() in risposta a questo evento, l'aggiornamento non verrà installato fino al riavvio di Chrome. Se nessun gestore è in ascolto di questo evento e l'estensione ha una pagina in background permanente, si comporta come se chrome.runtime.reload() venisse chiamato in risposta a questo evento.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
versione
stringa
Il numero della versione dell'aggiornamento disponibile.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Attivato quando viene stabilita una connessione da uno script utente da questa estensione.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(port: Port) => void
-
porta
-
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
Attivato quando viene inviato un messaggio da uno script utente associato alla stessa estensione.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
messaggio
Qualsiasi
-
mittente
-
sendResponse
funzione
Il parametro
sendResponse
ha il seguente aspetto:() => void
-
returns
booleano | non definito
-