Descrição
Use a API chrome.runtime
para recuperar o service worker, retornar detalhes sobre o manifesto e detectar e responder a eventos no ciclo de vida da extensão. Também é possível usar essa API para converter o caminho relativo de URLs em URLs totalmente qualificados.
A maioria dos membros dessa API não exige permissões. Essa permissão é necessária para connectNative()
, sendNativeMessage()
e onNativeConnect
.
O exemplo a seguir mostra como declarar a permissão "nativeMessaging"
no manifesto:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Conceitos e uso
A API Runtime oferece métodos para oferecer suporte a várias áreas que as extensões podem usar:
- Transmissão de mensagens
- Sua extensão pode se comunicar com diferentes contextos dentro dela e também com outras extensões usando estes métodos e eventos:
connect()
,onConnect
,onConnectExternal
,sendMessage()
,onMessage
eonMessageExternal
. Além disso, a extensão pode transmitir mensagens para aplicativos nativos no dispositivo do usuário usandoconnectNative()
esendNativeMessage()
.
- Como acessar metadados de extensões e plataformas
- Esses métodos permitem recuperar vários metadados específicos sobre a extensão e a
plataforma. Os métodos nessa categoria incluem
getManifest()
egetPlatformInfo()
. - Como gerenciar o ciclo de vida e as opções da extensão
- Com essas propriedades, você pode realizar algumas metaoperações na extensão e mostrar a página de opções.
Os métodos e eventos nessa categoria incluem
onInstalled
,onStartup
,openOptionsPage()
,reload()
,requestUpdateCheck()
esetUninstallURL()
. - Utilitários auxiliares
- Esses métodos fornecem utilitários, como a conversão de representações de recursos internos para
formatos externos. Os métodos nessa categoria incluem
getURL()
. - Utilitários do modo quiosque
- Esses métodos estão disponíveis apenas no ChromeOS e existem principalmente para oferecer suporte a implementações de quiosques.
Os métodos nessa categoria incluem
restart()
erestartAfterDelay()
`.
Comportamento da extensão descompactada
Quando uma extensão descompactada é recarregada, isso é tratado como uma atualização. Isso significa que o evento
chrome.runtime.onInstalled
será acionado com o motivo "update"
. Isso
inclui quando a extensão é recarregada com chrome.runtime.reload()
.
Casos de uso
Adicionar uma imagem a uma página da Web
Para que uma página da Web acesse um recurso hospedado em outro domínio, ela precisa especificar o URL completo do recurso
(por exemplo, <img src="https://example.com/logo.png">
). O mesmo vale para incluir um recurso de extensão em
uma página da Web. As duas diferenças são que os recursos da extensão precisam ser expostos como recursos
acessíveis da Web e que, normalmente, os scripts de conteúdo são responsáveis por injetar
recursos de extensão.
Neste exemplo, a extensão vai adicionar logo.png
à página em que o script
de conteúdo está sendo injetado usando runtime.getURL()
para criar um
URL totalmente qualificado. Mas primeiro, o recurso precisa ser declarado como um recurso acessível da Web no manifesto.
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);
}
Enviar dados de um script de conteúdo para o worker de serviço
É comum que os scripts de conteúdo de uma extensão precisem de dados gerenciados por outra parte da extensão, como o service worker. Assim como duas janelas do navegador abertas para a mesma página da Web, esses dois contextos não podem acessar diretamente os valores um do outro. Em vez disso, a extensão pode usar a transmissão de mensagens para coordenar esses diferentes contextos.
Neste exemplo, o script de conteúdo precisa de alguns dados do worker de serviço da extensão para
inicializar a interface. Para receber esses dados, ele transmite a mensagem get-user-data
definida pelo desenvolvedor
ao worker de serviço e responde com uma cópia das informações do usuário.
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);
}
});
Coletar feedback sobre a desinstalação
Muitas extensões usam pesquisas pós-desinstalação para entender como a extensão pode atender melhor os usuários e melhorar a retenção. O exemplo a seguir mostra como adicionar essa funcionalidade.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
Exemplos
Consulte a demonstração do Manifest V3: recursos acessíveis na Web para conferir mais exemplos da API Runtime.
Tipos
ContextFilter
Um filtro para corresponder a determinados contextos de extensão. Os contextos correspondentes precisam corresponder a todos os filtros especificados. Qualquer filtro que não seja especificado corresponde a todos os contextos disponíveis. Assim, um filtro de "{}" vai corresponder a todos os contextos disponíveis.
Propriedades
-
contextIds
string[] opcional
-
contextTypes
ContextType[] opcional
-
documentIds
string[] opcional
-
documentOrigins
string[] opcional
-
documentUrls
string[] opcional
-
frameIds
number[] opcional
-
navegação anônima
booleano opcional
-
tabIds
number[] opcional
-
windowIds
number[] opcional
ContextType
Enumeração
"TAB"
Especifica o tipo de contexto como uma guia
"POPUP"
Especifica o tipo de contexto como uma janela pop-up de extensão
"BACKGROUND"
Especifica o tipo de contexto como um worker de serviço.
"OFFSCREEN_DOCUMENT"
Especifica o tipo de contexto como um documento fora da tela.
"SIDE_PANEL"
Especifica o tipo de contexto como um painel lateral.
"DEVELOPER_TOOLS"
Especifica o tipo de contexto como ferramentas para desenvolvedores.
ExtensionContext
Um contexto que hospeda conteúdo da extensão.
Propriedades
-
contextId
string
Um identificador exclusivo para esse contexto
-
contextType
O tipo de contexto ao qual ele corresponde.
-
documentId
string opcional
Um UUID para o documento associado a esse contexto ou indefinido se ele não estiver hospedado em um documento.
-
documentOrigin
string opcional
A origem do documento associado a esse contexto ou indefinido se o contexto não estiver hospedado em um documento.
-
documentUrl
string opcional
O URL do documento associado a esse contexto ou indefinido se o contexto não estiver hospedado em um documento.
-
frameId
number
O ID do frame para este contexto ou -1 se ele não estiver hospedado em um frame.
-
navegação anônima
booleano
Indica se o contexto está associado a um perfil anônimo.
-
tabId
number
O ID da guia para esse contexto ou -1 se ele não estiver hospedado em uma guia.
-
windowId
number
O ID da janela para esse contexto ou -1 se esse contexto não estiver hospedado em uma janela.
MessageSender
Um objeto que contém informações sobre o contexto do script que enviou uma mensagem ou solicitação.
Propriedades
-
documentId
string opcional
Chrome 106 e versões mais recentesUm UUID do documento que abriu a conexão.
-
documentLifecycle
string opcional
Chrome 106 e versões mais recentesO ciclo de vida do documento que abriu a conexão no momento em que a porta foi criada. O estado do ciclo de vida do documento pode ter mudado desde a criação da porta.
-
frameId
número opcional
O frame que abriu a conexão. 0 para frames de nível superior, positivo para frames filhos. Ele só será definido quando
tab
for definido. -
id
string opcional
O ID da extensão que abriu a conexão, se houver.
-
nativeApplication
string opcional
Chrome 74 e versões mais recentesO nome do aplicativo nativo que abriu a conexão, se houver.
-
origem
string opcional
Chrome 80 e versões mais recentesA origem da página ou do frame que abriu a conexão. Ele pode variar de acordo com a propriedade de URL (por exemplo, "about:blank") ou pode ser opaco (por exemplo, iframes em sandbox). Isso é útil para identificar se a origem é confiável se não for possível saber imediatamente pelo URL.
-
tab
Guia opcional
O
tabs.Tab
que abriu a conexão, se houver. Essa propriedade só estará presente quando a conexão for aberta em uma guia (incluindo scripts de conteúdo) e somente se o receptor for uma extensão, não um app. -
tlsChannelId
string opcional
O ID do canal TLS da página ou do frame que abriu a conexão, se solicitado pela extensão e se disponível.
-
url
string opcional
O URL da página ou do frame que abriu a conexão. Se o remetente estiver em um iframe, ele será o URL do iframe, não o URL da página que o hospeda.
OnInstalledReason
O motivo pelo qual o evento está sendo enviado.
Enumeração
"install"
especifica o motivo do evento como uma instalação.
"update"
especifica o motivo do evento como uma atualização da extensão.
"chrome_update"
Especifica o motivo do evento como uma atualização do Chrome.
"shared_module_update"
Especifica o motivo do evento como uma atualização de um módulo compartilhado.
OnRestartRequiredReason
O motivo pelo qual o evento está sendo enviado. "app_update" é usado quando a reinicialização é necessária porque o aplicativo foi atualizado para uma versão mais recente. "os_update" é usado quando a reinicialização é necessária porque o navegador/SO foi atualizado para uma versão mais recente. "Periódico" é usado quando o sistema é executado por mais tempo do que o tempo de atividade permitido definido na política corporativa.
Enumeração
"app_update"
especifica o motivo do evento como uma atualização do app.
"os_update"
especifica o motivo do evento como uma atualização do sistema operacional.
"periodic"
especifica o motivo do evento como uma reinicialização periódica do app.
PlatformArch
A arquitetura do processador da máquina.
Enumeração
"arm"
Especifica a arquitetura do processador como arm.
"arm64"
especifica a arquitetura do processador como arm64.
"x86-32"
Especifica a arquitetura do processador como x86-32.
"x86-64"
Especifica a arquitetura do processador como x86-64.
"mips"
Especifica a arquitetura do processador como mips.
"mips64"
Especifica a arquitetura do processador como mips64.
PlatformInfo
Um objeto que contém informações sobre a plataforma atual.
Propriedades
-
arch
A arquitetura do processador da máquina.
-
nacl_arch
A arquitetura do cliente nativo. Isso pode ser diferente de arch em algumas plataformas.
-
os
O sistema operacional em que o Chrome está sendo executado.
PlatformNaclArch
A arquitetura do cliente nativo. Isso pode ser diferente de arch em algumas plataformas.
Enumeração
"arm"
Especifica a arquitetura do cliente nativo como arm.
"x86-32"
especifica a arquitetura do cliente nativo como x86-32.
"x86-64"
especifica a arquitetura do cliente nativo como x86-64.
"mips"
Especifica a arquitetura do cliente nativo como mips.
"mips64"
especifica a arquitetura do cliente nativo como mips64.
PlatformOs
O sistema operacional em que o Chrome está sendo executado.
Enumeração
"mac"
especifica o sistema operacional MacOS.
"win"
Especifica o sistema operacional Windows.
"android"
Especifica o sistema operacional Android.
"cros"
Especifica o sistema operacional Chrome.
"linux"
Especifica o sistema operacional Linux.
"openbsd"
Especifica o sistema operacional OpenBSD.
"fuchsia"
Especifica o sistema operacional Fuchsia.
Port
Um objeto que permite a comunicação bidirecional com outras páginas. Consulte Conexões de longa duração para mais informações.
Propriedades
-
nome
string
O nome da porta, conforme especificado na chamada para
runtime.connect
. -
onDisconnect
Evento<functionvoidvoid>
É disparado quando a porta é desconectada das outras extremidades.
runtime.lastError
pode ser definido se a porta foi desconectada por um erro. Se a porta for fechada por desconexão, esse evento será somente acionado na outra extremidade. Esse evento é acionado no máximo uma vez (consulte também Vida útil da porta).A função
onDisconnect.addListener
é semelhante a esta:(callback: function) => {...}
-
onMessage
Evento<functionvoidvoid>
Esse evento é acionado quando postMessage é chamado pela outra extremidade da porta.
A função
onMessage.addListener
é semelhante a esta:(callback: function) => {...}
-
remetente
MessageSender opcional
Essa propriedade só estará presente nas portas transmitidas para os listeners onConnect / onConnectExternal / onConnectNative.
-
desconectar
void
Desconecte a porta imediatamente. Chamar
disconnect()
em uma porta já desconectada não tem efeito. Quando uma porta é desconectada, nenhum evento novo é enviado para ela.A função
disconnect
é semelhante a esta:() => {...}
-
postMessage
void
Enviar uma mensagem para a outra extremidade da porta. Se a porta for desconectada, um erro será gerado.
A função
postMessage
é semelhante a esta:(message: any) => {...}
-
mensagem
qualquer um
Chrome 52 e versões mais recentesA mensagem a ser enviada. Esse objeto precisa ser JSONificável.
-
RequestUpdateCheckStatus
Resultado da verificação de atualização.
Enumeração
"Limitada"
especifica que a verificação de status foi limitada. Isso pode ocorrer após verificações repetidas em um curto período.
"no_update"
especifica que não há atualizações disponíveis para instalação.
"update_available"
especifica que há uma atualização disponível para instalação.
Propriedades
id
O ID da extensão/do app.
Tipo
string
lastError
Será preenchido com uma mensagem de erro se a chamada de uma função da API falhar. Caso contrário, será indefinido. Isso é definido apenas no escopo do callback da função. Se um erro for produzido, mas runtime.lastError
não for acessado no callback, uma mensagem será registrada no console listando a função da API que produziu o erro. As funções da API que retornam promessas não definem essa propriedade.
Tipo
objeto
Propriedades
-
mensagem
string opcional
Detalhes sobre o erro que ocorreu.
Métodos
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
Tenta conectar listeners em uma extensão (como a página em segundo plano) ou em outras extensões/apps. Isso é útil para scripts de conteúdo que se conectam aos processos de extensão, comunicação entre apps/extensões e mensagens da Web. Isso não se conecta a nenhum listener em um script de conteúdo. As extensões podem se conectar a scripts de conteúdo incorporados em guias usando tabs.connect
.
Parâmetros
-
extensionId
string opcional
O ID da extensão a ser conectado. Se omitido, uma tentativa de conexão será feita com sua própria extensão. Obrigatório se você enviar mensagens de uma página da Web para mensagens da Web.
-
connectInfo
objeto opcional
-
includeTlsChannelId
booleano opcional
Indica se o ID do canal TLS será transmitido para onConnectExternal para processos que estão detectando o evento de conexão.
-
nome
string opcional
Será transmitido para onConnect para processos que estão detectando o evento de conexão.
-
Retorna
-
Porta por onde as mensagens podem ser enviadas e recebidas. O evento onDisconnect da porta é acionado se a extensão não existir.
connectNative()
chrome.runtime.connectNative(
application: string,
)
Conecta-se a um aplicativo nativo na máquina host. Esse método exige a permissão "nativeMessaging"
. Consulte Mensagens nativas para mais informações.
Parâmetros
-
aplicativo
string
O nome do aplicativo registrado a ser conectado.
Retorna
-
Porta pela qual as mensagens podem ser enviadas e recebidas com o aplicativo
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Recupera o objeto "window" do JavaScript para a página em segundo plano em execução dentro da extensão/atualização atual. Se a página em segundo plano for uma página de evento, o sistema vai garantir que ela seja carregada antes de chamar o callback. Se não houver uma página em segundo plano, um erro será definido.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem este formato:(backgroundPage?: Window) => void
-
backgroundPage
Janela opcional
O objeto "window" do JavaScript para a página em segundo plano.
-
Retorna
-
Promise<Window | undefined>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Busca informações sobre contextos ativos associados a essa extensão
Parâmetros
-
filtro
Um filtro para encontrar contextos correspondentes. Um contexto corresponde se corresponder a todos os campos especificados no filtro. Qualquer campo não especificado no filtro corresponde a todos os contextos.
-
callback
função opcional
O parâmetro
callback
tem este formato:(contexts: ExtensionContext[]) => void
-
contexts
Os contextos correspondentes, se houver.
-
Retorna
-
Promise<ExtensionContext[]>
As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
getManifest()
chrome.runtime.getManifest()
Retorna detalhes sobre o app ou a extensão do manifesto. O objeto retornado é uma serialização do arquivo de manifesto completo.
Retorna
-
objeto
Os detalhes do manifesto.
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
Retorna uma entrada de diretório para o diretório do pacote.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem este formato:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Retorna
-
Promise<DirectoryEntry>
Chrome 122 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Retorna informações sobre a plataforma atual.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem este formato:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Retorna
-
Promise<PlatformInfo>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
getURL()
chrome.runtime.getURL(
path: string,
)
Converte um caminho relativo em um diretório de instalação de app/extensão em um URL totalmente qualificado.
Parâmetros
-
caminho
string
Um caminho para um recurso em um app/extensão expresso em relação ao diretório de instalação.
Retorna
-
string
O URL totalmente qualificado para o recurso.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
Abra a página de opções da extensão, se possível.
O comportamento exato pode depender da chave options_ui
ou options_page
do manifesto ou do suporte do Chrome no momento. Por exemplo, a página pode ser aberta em uma nova guia, em chrome://extensions, em um app ou pode apenas focar uma página de opções aberta. Ela nunca vai causar a atualização da página do autor da chamada.
Se a extensão não declarar uma página de opções ou se o Chrome não conseguir criar uma por algum motivo, o callback vai definir lastError
.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
Retorna
-
Promise<void>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
reload()
chrome.runtime.reload()
Recarrega o app ou a extensão. Esse método não é compatível com o modo quiosque. Para o modo quiosque, use o método chrome.runtime.restart().
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
Solicita que uma verificação de atualização imediata seja feita para este app/extensão.
Importante: a maioria das extensões/apps não precisa usar esse método, já que o Chrome já faz verificações automáticas a cada poucas horas, e você pode acompanhar o evento runtime.onUpdateAvailable
sem precisar chamar requestUpdateCheck.
Esse método só é adequado para chamar em circunstâncias muito limitadas, como quando sua extensão se comunica com um serviço de back-end e ele determina que a versão da extensão do cliente está muito desatualizada e você quer solicitar que o usuário faça a atualização. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer recorrente, provavelmente serve apenas para desperdiçar recursos do cliente, da rede e do servidor.
Observação: quando chamada com um callback, em vez de retornar um objeto, essa função retorna as duas propriedades como argumentos separados transmitidos ao callback.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem este formato:(result: object) => void
-
resultado
objeto
Chrome 109 e versões mais recentesObjeto RequestUpdateCheckResult que contém o status da verificação de atualização e todos os detalhes do resultado, se houver uma atualização disponível
-
status
Resultado da verificação de atualização.
-
version
string opcional
Se uma atualização estiver disponível, ela vai conter a versão da atualização disponível.
-
-
Retorna
-
Promise<object>
Chrome 109 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
restart()
chrome.runtime.restart()
Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque. Caso contrário, não vai funcionar.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Reinicia o dispositivo ChromeOS quando o app é executado no modo quiosque após os segundos especificados. Se for chamada novamente antes do término do tempo, a reinicialização será adiada. Se for chamado com um valor de -1, a reinicialização será cancelada. Não há operação no modo que não é quiosque. Ela só pode ser chamada repetidamente pela primeira extensão para invocar essa API.
Parâmetros
-
segundos
number
Tempo de espera em segundos antes da reinicialização do dispositivo ou -1 para cancelar uma reinicialização programada.
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
Retorna
-
Promise<void>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Envia uma única mensagem para listeners de eventos na sua extensão ou em uma extensão/um app diferente. É semelhante a runtime.connect
, mas envia apenas uma mensagem com uma resposta opcional. Se o envio for para sua extensão, o evento runtime.onMessage
será acionado em todos os frames da sua extensão (exceto o frame do remetente) ou runtime.onMessageExternal
, se for uma extensão diferente. As extensões não podem enviar mensagens para scripts de conteúdo usando esse método. Para enviar mensagens a scripts de conteúdo, use tabs.sendMessage
.
Parâmetros
-
extensionId
string opcional
O ID da extensão para a qual a mensagem será enviada. Se omitido, a mensagem será enviada para sua própria extensão/app. Obrigatório se você estiver enviando mensagens de uma página da Web para mensagens da Web.
-
mensagem
qualquer um
A mensagem a ser enviada. Essa mensagem precisa ser um objeto JSON.
-
opções
objeto opcional
-
includeTlsChannelId
booleano opcional
Indica se o ID do canal TLS será transmitido para onMessageExternal para processos que estão detectando o evento de conexão.
-
-
callback
função opcional
Chrome 99 e versões mais recentesO parâmetro
callback
tem este formato:(response: any) => void
-
resposta
qualquer um
O objeto de resposta JSON enviado pelo gerenciador da mensagem. Se ocorrer um erro ao se conectar à extensão, o callback será chamado sem argumentos e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Promise<any>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Enviar uma única mensagem para um aplicativo nativo. Esse método exige a permissão "nativeMessaging"
.
Parâmetros
-
aplicativo
string
O nome do host de mensagens nativas.
-
mensagem
objeto
A mensagem que será transmitida ao host de mensagens nativo.
-
callback
função opcional
Chrome 99 e versões mais recentesO parâmetro
callback
tem este formato:(response: any) => void
-
resposta
qualquer um
A mensagem de resposta enviada pelo host de mensagens nativas. Se ocorrer um erro ao se conectar ao host de mensagens nativo, o callback será chamado sem argumentos e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Promise<any>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
Define o URL a ser visitado após a desinstalação. Isso pode ser usado para limpar dados do lado do servidor, fazer análises e implementar pesquisas. Máximo de 1.023 caracteres.
Parâmetros
-
url
string
URL a ser aberto após a desinstalação da extensão. Esse URL precisa ter um esquema http: ou https:. Definir uma string vazia para não abrir uma nova guia na desinstalação.
-
callback
função opcional
Chrome 45 e versões mais recentesO parâmetro
callback
tem este formato:() => void
Retorna
-
Promise<void>
Chrome 99 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
Eventos
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Use runtime.onRestartRequired
.
É acionado quando uma atualização do Chrome está disponível, mas não é instalada imediatamente porque é necessária uma reinicialização do navegador.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
É acionado quando uma conexão é feita de um processo de extensão ou de um script de conteúdo (por runtime.connect
).
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
É acionado quando uma conexão é feita de outra extensão (por runtime.connect
) ou de um site da Web com conexão externa.
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Acionado quando uma conexão é feita de um aplicativo nativo. Esse evento requer a permissão "nativeMessaging"
. Ele só é compatível com o Chrome OS.
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
É acionado quando a extensão é instalada pela primeira vez, quando a extensão é atualizada para uma nova versão e quando o Chrome é atualizado para uma nova versão.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(details: object) => void
-
detalhes
objeto
-
id
string opcional
Indica o ID da extensão do módulo compartilhado importado que foi atualizada. Isso só vai estar presente se "reason" for "shared_module_update".
-
previousVersion
string opcional
Indica a versão anterior da extensão, que acabou de ser atualizada. Isso só vai estar presente se "reason" for "update".
-
reason
O motivo pelo qual o evento está sendo enviado.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
É acionado quando uma mensagem é enviada de um processo de extensão (por runtime.sendMessage
) ou de um script de conteúdo (por tabs.sendMessage
).
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem este formato:() => void
-
retorna
booleano | indefinido
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
É acionado quando uma mensagem é enviada de outra extensão (por runtime.sendMessage
). Não pode ser usado em um script de conteúdo.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem este formato:() => void
-
retorna
booleano | indefinido
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
É acionado quando um app ou o dispositivo em que ele é executado precisa ser reiniciado. O app precisa fechar todas as janelas no momento mais conveniente para que a reinicialização aconteça. Se o app não fizer nada, uma reinicialização será aplicada após um período de carência de 24 horas. No momento, esse evento só é acionado para apps de quiosque do Chrome OS.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(reason: OnRestartRequiredReason) => void
-
reason
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
É acionado quando um perfil com essa extensão instalada é iniciado pela primeira vez. Esse evento não é acionado quando um perfil anônimo é iniciado, mesmo que a extensão esteja operando no modo de navegação anônima "dividida".
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
É enviado para a página do evento pouco antes de ser descarregado. Isso dá à extensão a oportunidade de fazer uma limpeza. Como a página está sendo removida, não há garantia de que as operações assíncronas iniciadas durante o processamento desse evento serão concluídas. Se mais atividade para a página do evento ocorrer antes que ela seja descarregada, o evento onSuspendCanceled será enviado e a página não será descarregada.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
É enviado após onSuspend para indicar que o app não será removido.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
É acionado quando uma atualização está disponível, mas não é instalada imediatamente porque o app está em execução. Se você não fizer nada, a atualização será instalada na próxima vez que a página em segundo plano for descarregada. Se você quiser que ela seja instalada mais cedo, chame explicitamente chrome.runtime.reload(). Se a extensão estiver usando uma página em segundo plano persistente, ela nunca será descarregada. Portanto, a menos que você chame chrome.runtime.reload() manualmente em resposta a esse evento, a atualização não será instalada até a próxima reinicialização do Chrome. Se nenhum manipulador estiver detectando esse evento e a extensão tiver uma página de segundo plano persistente, ela vai se comportar como se chrome.runtime.reload() fosse chamado em resposta a esse evento.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(details: object) => void
-
detalhes
objeto
-
version
string
O número da versão da atualização disponível.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Acionado quando uma conexão é feita de um script do usuário desta extensão.
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
É acionado quando uma mensagem é enviada de um script do usuário associado à mesma extensão.
Parâmetros
-
callback
função
O parâmetro
callback
tem este formato:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem este formato:() => void
-
retorna
booleano | indefinido
-