chrome.runtime

Descrizione

Usa l'API chrome.runtime per recuperare il service worker, restituire i dettagli del manifest, ascoltare gli eventi e rispondere agli eventi del ciclo di vita dell'estensione. Puoi utilizzare questa API anche per convertire il percorso relativo degli URL in URL completi.

La maggior parte dei membri di questa API non richiede alcuna autorizzazione. Questa autorizzazione è necessaria per connectNative(), sendNativeMessage() e onNativeConnect.

L'esempio seguente mostra come dichiarare l'autorizzazione "nativeMessaging" nel file manifest:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Concetti e utilizzo

L'API Runtime fornisce metodi per supportare una serie di aree che le tue estensioni possono utilizzare:

Trasmissione dei messaggi
L'estensione può comunicare con diversi contesti al suo interno e anche con altre estensioni, utilizzando i seguenti metodi ed eventi: connect(), onConnect onConnectExternal, sendMessage(), onMessage e onMessageExternal. Inoltre, l'estensione può passare messaggi ad applicazioni native sul dispositivo dell'utente utilizzando connectNative() e sendNativeMessage().
di Gemini Advanced.
.
Accesso ai metadati di estensioni e piattaforma
Questi metodi consentono di recuperare diversi metadati specifici sull'estensione e completamente gestita. 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 di visualizzare la pagina delle opzioni. I metodi e gli eventi in questa categoria includono onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() e setUninstallURL().
Utilità helper
Questi metodi forniscono utilità come la conversione delle rappresentazioni delle risorse interne 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()`.

Comportamento delle estensioni non pacchettizzate

Quando un'estensione non pacchettizzata viene ricaricata, questa viene considerata come un aggiornamento. Ciò significa che L'evento chrome.runtime.onInstalled verrà attivato con il motivo "update". Questo include quando l'estensione viene ricaricata con chrome.runtime.reload().

Casi d'uso

Aggiungere un'immagine a una pagina web

Una pagina web può accedere a un asset ospitato su un altro dominio, deve specificare l'URL completo della risorsa (ad es. <img src="https://example.com/logo.png">). Lo stesso vale per includere un asset estensione una pagina web. Le due differenze sono che gli asset dell'estensione devono essere esposti come accessibili e che in genere gli script di contenuti sono responsabili dell'inserimento asset delle estensioni.

In questo esempio, l'estensione aggiungerà logo.png alla pagina contenuto viene iniettato in utilizzando runtime.getURL() per creare uno URL completo. Prima, però, l'asset deve essere dichiarato come risorsa accessibile sul web nel file 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 i dati da uno script di contenuti al service worker

È comune che gli script di contenuti di un'estensione richiedano dati gestiti da un'altra parte dell'estensione. come il service worker. Proprio come due finestre del browser aperte nella stessa pagina web, queste due contesti non possono accedere direttamente ai valori degli altri. L'estensione può invece utilizzare messaggi per coordinarsi tra questi diversi contesti.

In questo esempio, lo script dei contenuti richiede alcuni dati dal service worker dell'estensione per per inizializzare la rispettiva UI. Per ottenere questi dati, trasmette il messaggio get-user-data definito dallo sviluppatore al service worker, che 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);
});

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);
  }
});

Raccogliere feedback sulla disinstallazione

Molte estensioni ricorrono ai sondaggi post-disinstallazione per capire in che modo l'estensione potrebbe essere più adatta alle sue 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

Vedi la demo di Manifest V3 - Web Accessible Resources per altri esempi di API Runtime.

Tipi

ContextFilter

Chrome 114 e versioni successive .

Un filtro per trovare una corrispondenza con determinati contesti di estensione. I contesti di corrispondenza devono corrispondere a tutti i filtri specificati. qualsiasi filtro non specificato corrisponde a tutti i contesti disponibili. In questo modo, un filtro di "{}" corrisponderà a tutti i contesti disponibili.

Proprietà

  • contextIds

    string[] facoltativo

  • contextTypes

    ContextType[] facoltativo

  • documentIds

    string[] facoltativo

  • documentOrigins

    string[] facoltativo

  • documentUrls

    string[] facoltativo

  • frameIds

    numero[] facoltativo

  • in incognito

    booleano facoltativo

  • tabIds

    numero[] facoltativo

  • windowIds

    numero[] facoltativo

ContextType

Chrome 114 e versioni successive .

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

Chrome 114 e versioni successive .

Un contesto che ospita contenuti di estensioni.

Proprietà

  • contextId

    stringa

    Un identificatore univoco per questo contesto

  • contextType

    ContextType

    Il tipo di contesto a cui corrisponde.

  • documentId

    stringa facoltativo

    Un UUID per il documento associato a questo contesto oppure non definito se il contesto non è ospitato in un documento.

  • documentOrigin

    stringa facoltativo

    L'origine del documento associato a questo contesto oppure non definita se il contesto non è ospitato in un documento.

  • documentUrl

    stringa facoltativo

    L'URL del documento associato a questo contesto oppure 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

    booleano

    Se il contesto è associato a un profilo in incognito.

  • tabId

    numero

    L'ID della scheda per questo contesto o -1 se il contesto non è ospitato in una scheda.

  • windowId

    numero

    L'ID della finestra per questo contesto o -1 se il 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 successive .

    Un UUID del documento che ha aperto la connessione.

  • documentLifecycle

    stringa facoltativo

    Chrome 106 e versioni successive .

    Il 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 dopo la 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 è impostato tab.

  • id

    stringa facoltativo

    L'ID dell'estensione che ha aperto la connessione, se presente.

  • nativeApplication

    stringa facoltativo

    Chrome 74 e versioni successive .

    Il nome dell'applicazione nativa che ha aperto la connessione, se presente.

  • origine

    stringa facoltativo

    Chrome 80 e versioni successive .

    L'origine della pagina o del frame che ha aperto la connessione. Può variare rispetto alla proprietà dell'URL (ad es. about:blank) o essere opaco (ad es. iframe con sandbox). Ciò è utile per determinare se l'origine può essere considerata attendibile se non siamo in grado di distinguerlo immediatamente dall'URL.

  • tab

    Scheda facoltativa

    Il 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

Chrome 44 e versioni successive .

Il motivo per cui questo evento viene inviato.

Enum

"install"
Specifica il motivo dell'evento come installazione.

"update"
Specifica il motivo dell'evento come un aggiornamento dell'estensione.

&quot;chrome_update&quot;
Il motivo dell'evento è un aggiornamento di Chrome.

"shared_module_update"
Specifica il motivo dell'evento come un aggiornamento a un modulo condiviso.

OnRestartRequiredReason

Chrome 44 e versioni successive .

Il motivo per cui viene inviato l'evento. "app_update" viene utilizzato quando è necessario il riavvio perché l'applicazione viene aggiornata a una versione più recente. "os_update" viene utilizzato quando è necessario il riavvio perché il browser o il sistema operativo viene aggiornato a una versione più recente. "periodico" viene utilizzata quando il sistema viene eseguito per un tempo di attività superiore a quello consentito nei criteri aziendali.

Enum

"app_update"
Specifica il motivo dell'evento come un aggiornamento dell'app.

&quot;os_update&quot;
Specifica il motivo dell'evento come un aggiornamento del sistema operativo.

"periodic"
Specifica il motivo dell'evento come un riavvio periodico dell'app.

PlatformArch

Chrome 44 e versioni successive .

L'architettura del processore della macchina.

Enum

"arm"
Specifica l'architettura di elaborazione come gruppo.

"arm64"
Specifica l'architettura di processo come arm64.

"x86-32"
Specifica l'architettura dell'elaboratore come x86-32.

"x86-64"
Specifica l'architettura dell'elaboratore come x86-64.

"mips"
Specifica l'architettura di processo come mips.

"mips64"
Specifica l'architettura di processo come mips64.

PlatformInfo

Un oggetto contenente informazioni sulla piattaforma attuale.

Proprietà

  • L'architettura del processore della macchina.

  • nacl_arch

    PlatformNaclArch

    L'architettura del client nativo. Potrebbe essere diverso da come arch su alcune piattaforme.

  • sistema operativo

    PlatformOs

    Il sistema operativo su cui è in esecuzione Chrome.

PlatformNaclArch

Chrome 44 e versioni successive .

L'architettura del client nativo. Potrebbe essere diverso da come arch su alcune piattaforme.

Enum

"arm"
Specifica l'architettura nativa del client 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 nativa del client come mips.

"mips64"
Specifica l'architettura client nativa come mips64.

PlatformOs

Chrome 44 e versioni successive .

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.

&quot;openbsd&quot;
Specifica il sistema operativo OpenBSD.

"fuchsia"
Specifica il sistema operativo Fuchsia.

Port

Un 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>

    Attivato quando la porta è disconnessa dall'altra estremità. Se la porta è stata disconnessa a causa di un errore è possibile impostare runtime.lastError. Se la porta viene chiusa tramite scollega, questo evento viene attivato solo dall'altra estremità. Questo evento viene attivato al massimo una volta (vedi anche Durata della porta).

    La funzione onDisconnect.addListener ha questo aspetto: 

    (callback: function) => {...}

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

      (port: Port) => void

  • onMessage

    Evento<functionvoidvoid>

    Questo evento viene attivato quando postMessage viene chiamato dall'altra estremità della porta.

    La funzione onMessage.addListener ha questo aspetto: 

    (callback: function) => {...}

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

      (message: any, port: Port) => void

      • messaggio

        qualsiasi

      • porta

        Porta

  • mittente

    MessageSender facoltativo

    Questa proprietà sarà presente solo sulle porte trasmesse ai listener onConnect / onConnectExternal / onConnectNative.

  • disconnetti

    null

    Scollega immediatamente la porta. Chiamare disconnect() su una porta già disconnessa non ha alcun effetto. Quando una porta viene disconnessa, a questa porta non verranno inviati nuovi eventi.

    La funzione disconnect ha questo aspetto: 

    () => {...}

  • postMessage

    null

    Invia un messaggio all'altra estremità della porta. Se la porta è disconnessa, viene generato un errore.

    La funzione postMessage ha questo aspetto: 

    (message: any) => {...}

    • messaggio

      qualsiasi

      Chrome 52 e versioni successive .

      Il messaggio da inviare. Questo oggetto deve essere verificabile tramite JSON.

RequestUpdateCheckStatus

Chrome 44 e versioni successive .

Risultato del controllo di aggiornamenti.

Enum

"throttled"
Specifica che il controllo dello stato è stato limitato. Questo può verificarsi dopo controlli ripetuti entro 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 o dell'app.

Tipo

stringa

lastError

Compilato con un messaggio di errore se la chiamata di una funzione API non riesce. altrimenti indefinito. Viene definito solo nell'ambito del callback di quella funzione. Se viene generato un errore, ma non si accede 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 sull'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. Questa funzionalità è utile per gli script di contenuti che si connettono ai rispettivi processi di estensioni, per le comunicazioni tra app/estensioni e per i messaggi web. Tieni presente che questa operazione non si connette a nessun listener in uno script di contenuti. Le estensioni possono collegarsi 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 si inviano messaggi da una pagina web per la messaggistica web.

  • connectInfo

    oggetto facoltativo

    • includeTlsChannelId

      booleano facoltativo

      Indica se l'ID canale TLS verrà passato a onConnectExternal per i processi che stanno ascoltando l'evento di connessione.

    • nome

      stringa facoltativo

      Verrà passato a onConnect per i processi che stanno ascoltando l'evento di connessione.

Resi

  • Porta attraverso la quale possono essere inviati e ricevuti i messaggi. L'evento onDisconnect della porta viene attivato se l'estensione non esiste.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Si connette a un'applicazione nativa nel computer host. Questo metodo richiede l'autorizzazione "nativeMessaging". Per ulteriori informazioni, consulta la sezione Messaggistica nativa.

Parametri

  • applicazione

    stringa

    Il nome dell'applicazione registrata a cui vuoi collegarti.

Resi

  • Porta attraverso la quale è possibile inviare e ricevere messaggi con l'applicazione

getBackgroundPage()

Promesso Solo in primo piano 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Recupera la "finestra" JavaScript per la pagina di sfondo in esecuzione all'interno dell'estensione/dell'app corrente. Se la pagina in background è una pagina di evento, il sistema verificherà che venga caricata prima di chiamare il callback. Se non è presente 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

      La "finestra" JavaScript per la pagina di sfondo.

Resi

  • Promise&lt;Window | non definito>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getContexts()

Promesso Chrome 116 e versioni successive MV3 o versioni successive 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Recupera le informazioni sui contesti attivi associati a questa estensione

Parametri

  • filtro

    ContextFilter

    Un filtro per trovare i contesti corrispondenti. Un contesto viene trovato 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

Resi

  • Promise&lt;ExtensionContext[]&gt;

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getManifest()

chrome.runtime.getManifest()

Restituisce i dettagli sull'app o sull'estensione dal file manifest. L'oggetto restituito è una serializzazione del file manifest completo.

Resi

  • oggetto

    Dettagli del file manifest.

getPackageDirectoryEntry()

Promesso Solo in primo piano 
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

Resi

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getPlatformInfo()

Promesso .
chrome.runtime.getPlatformInfo(
  callback?: function,
)

Restituisce informazioni sulla piattaforma corrente.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (platformInfo: PlatformInfo) => void

Resi

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al 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 directory di installazione corrispondente.

Resi

  • stringa

    L'URL completo della risorsa.

openOptionsPage()

Promesso .
chrome.runtime.openOptionsPage(
  callback?: function,
)

Se possibile, apri la pagina delle opzioni dell'estensione.

Il comportamento preciso può 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 da ciò che Chrome supporta al momento. Ad esempio, la pagina potrebbe essere aperta in una nuova scheda, all'interno di chrome://extensions, all'interno di un'app oppure impostare lo stato attivo su una pagina delle opzioni aperta. La pagina del chiamante non verrà mai ricaricata.

Se la tua estensione non dichiara una pagina delle opzioni o se Chrome non è riuscito a crearne una per qualche altro motivo, il callback verrà impostato su lastError.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al 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()

Promesso .
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Richiedi un controllo immediato degli aggiornamenti per questa app/estensione.

Importante: la maggior parte delle estensioni e delle app non dovrebbe utilizzare questo metodo, in quanto Chrome esegue già controlli automatici a intervalli di alcune ore e puoi ascoltare l'evento runtime.onUpdateAvailable senza dover chiamare requestUpdateCheck.

Questo metodo è appropriato solo per effettuare una chiamata in circostanze molto limitate, ad esempio se la tua estensione comunica con un servizio di backend e quest'ultimo ha stabilito che la versione dell'estensione client è molto obsoleta e vorresti chiedere a un utente di eseguire l'aggiornamento. La maggior parte degli altri utilizzi di requestUpdateCheck, come chiamarlo incondizionatamente basato su un timer ricorrente, probabilmente serve solo a sprecare risorse del client, della rete e del server.

Nota: quando viene chiamata 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 successive .

      Oggetto RequestUpdateCheckResult che contiene lo stato del controllo degli aggiornamenti e qualsiasi dettaglio del risultato, se è disponibile un aggiornamento

      • Risultato del controllo di aggiornamenti.

      • versione

        stringa facoltativo

        Se è disponibile un aggiornamento, questo contiene la versione dell'aggiornamento disponibile.

Resi

  • Promise&lt;object&gt;

    Chrome 109 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

restart()

chrome.runtime.restart()

Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk. Altrimenti, è autonomo.

restartAfterDelay()

Promesso Chrome 53 e versioni successive 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Riavvia il dispositivo ChromeOS quando l'app viene eseguita in modalità kiosk dopo i secondi specificati. Se la chiamata viene richiamata prima della fine dell'orario, il riavvio verrà ritardato. Se la chiamata è impostata con il valore -1, il riavvio verrà annullato. È un'operazione autonoma in modalità kiosk. Può essere chiamato ripetutamente solo dalla 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

Resi

  • Promesso<void>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

sendMessage()

Promesso .
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Invia un singolo messaggio ai listener di eventi all'interno dell'estensione o di un'estensione/app diversa. Simile a runtime.connect, ma invia un solo messaggio, con una risposta facoltativa. Se lo invii all'estensione, l'evento runtime.onMessage verrà attivato in ogni frame dell'estensione (ad eccezione di quello del mittente) o runtime.onMessageExternal, se è un'estensione diversa. Tieni presente che le estensioni non possono inviare messaggi a script di contenuti utilizzando questo metodo. Per inviare messaggi agli 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 si inviano messaggi da una pagina web per la messaggistica web.

  • messaggio

    qualsiasi

    Il messaggio da inviare. Questo messaggio deve essere un oggetto verificabile con JSON.

  • opzioni

    oggetto facoltativo

    • includeTlsChannelId

      booleano facoltativo

      Indica se l'ID canale TLS verrà passato a onMessageExternal per i processi che stanno ascoltando l'evento di connessione.

  • callback

    funzione facoltativa

    Chrome 99 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    (response: any) => void

    • risposta

      qualsiasi

      L'oggetto risposta JSON inviato dal gestore del messaggio. Se si verifica un errore durante la connessione all'estensione, il callback viene chiamato senza argomenti e runtime.lastError viene impostato sul messaggio di errore.

Resi

  • Promesso<qualsiasi>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

sendNativeMessage()

Promesso .
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Invia un singolo messaggio a un'applicazione nativa. Questo metodo richiede l'autorizzazione "nativeMessaging".

Parametri

  • applicazione

    stringa

    Il nome dell'host di messaggistica nativo.

  • messaggio

    oggetto

    Il messaggio che verrà passato all'host di messaggistica nativo.

  • callback

    funzione facoltativa

    Chrome 99 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    (response: any) => void

    • risposta

      qualsiasi

      Il messaggio di risposta inviato dall'host di messaggistica nativo. 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.

Resi

  • Promesso<qualsiasi>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

setUninstallURL()

Promesso .
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Imposta l'URL da visitare al momento della disinstallazione. Può essere utilizzato per pulire i dati lato server, eseguire analisi e implementare sondaggi. Massimo 1023 caratteri.

Parametri

  • url

    stringa

    URL da aprire dopo la disinstallazione dell'estensione. Questo 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 successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

Eventi

onBrowserUpdateAvailable

Obsoleta
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Utilizza runtime.onRestartRequired.

Attivato quando è disponibile un aggiornamento di Chrome, ma non viene installato immediatamente perché è necessario riavviare il 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

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Attivato quando viene stabilita una connessione da un'altra estensione (di runtime.connect) o da un sito web collegabile esternamente.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onConnectNative

Chrome 76 e versioni successive .
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Attivato quando viene stabilita una connessione da un'applicazione nativa. Questo evento richiede l'autorizzazione "nativeMessaging". È supportata solo su ChromeOS.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Attivato alla prima installazione dell'estensione, quando l'estensione viene aggiornata a una nuova versione e quando Chrome viene aggiornato 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 condiviso importata che è stata aggiornata. È presente solo se "motivo" (motivo) è "shared_module_update".

      • previousVersion

        stringa facoltativo

        Indica la versione precedente dell'estensione, che è stata appena aggiornata. È presente solo se "motivo" (motivo) è "update".

      • Il motivo per cui questo evento viene inviato.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Attivato 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

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      () => void

    • returns

      boolean | non definito

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Attivato quando un messaggio viene inviato da un'altra estensione (da runtime.sendMessage). Non possono essere utilizzate 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

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      () => void

    • returns

      boolean | non definito

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Attivato quando un'app o il dispositivo su cui è in esecuzione devono essere riavviati. Per consentire il riavvio, l'app dovrebbe chiudere tutte le finestre non appena possibile. Se l'app non esegue alcuna azione, verrà applicato un riavvio forzato una volta trascorso un periodo di tolleranza di 24 ore. Al momento, questo evento viene attivato solo per le app kiosk di ChromeOS.

Parametri

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Attivato quando viene avviato un profilo con questa estensione installata per la prima volta. Questo evento non viene attivato quando viene avviato un profilo in incognito, anche se l'estensione è "suddivisa" modalità di navigazione in incognito.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Viene inviato alla pagina dell'evento appena prima dell'unload. In questo modo, l'estensione potrà eseguire un po' di pulizia. Tieni presente che, poiché è in corso l'unload della pagina, non è garantito il completamento di 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 la sospensione di un'app per indicare che l'app non verrà scaricata.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

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 prossima volta che la pagina in background viene scaricata. Se vuoi che venga installata prima, puoi chiamare esplicitamente chrome.runtime.reload(). Se la tua estensione utilizza una pagina in background permanente, ovviamente quest'ultima non viene mai scaricata. Di conseguenza, a meno che non chiami manualmente chrome.runtime.reload() in risposta a questo evento, l'aggiornamento non verrà installato fino al successivo 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 di versione dell'aggiornamento disponibile.

onUserScriptConnect

Chrome 115 e versioni successive MV3 o versioni successive 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Attivato quando viene stabilita una connessione da uno script utente di questa estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (port: Port) => void

onUserScriptMessage

Chrome 115 e versioni successive MV3 o versioni successive 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Attivato quando un messaggio viene inviato 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

      MessageSender

    • sendResponse

      funzione

      Il parametro sendResponse ha il seguente aspetto: 

      () => void

    • returns

      boolean | non definito