Descrição
Use a API chrome.runtime
para extrair 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 precisa de 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 suas 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ão e plataforma
- Esses métodos permitem que você recupere várias partes específicas de metadados sobre a extensão e a
plataforma. Os métodos nesta categoria incluem
getManifest()
egetPlatformInfo()
. - Como gerenciar o ciclo de vida e as opções de extensões
- Essas propriedades permitem realizar algumas metaoperações na extensão e exibir a página de opções.
Os métodos e eventos nesta categoria incluem
onInstalled
,onStartup
,openOptionsPage()
,reload()
,requestUpdateCheck()
esetUninstallURL()
. - Utilitários auxiliares
- Esses métodos oferecem utilitários, como a conversão de representações de recursos internos para
formatos externos. Os métodos nesta 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 quiosque.
Os métodos nesta categoria incluem
restart()
erestartAfterDelay()
.
Comportamento da extensão descompactada
Quando uma extensão descompactada é recarregada, ela é tratada como uma atualização. Isso significa que o evento
chrome.runtime.onInstalled
será disparado 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 pela Web e que normalmente os scripts de conteúdo são responsáveis por injetar
recursos de extensão.
Neste exemplo, a extensão 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 pela 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 service worker
É 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. Da mesma forma que duas janelas do navegador abertas na 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 service worker da extensão para inicializar a IU. Para conseguir esses dados, ele transmite a mensagem get-user-data
definida pelo desenvolvedor
ao service worker 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 elas podem atender melhor aos usuários e aumentar 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 o Manifest V3 - Demonstração de recursos acessíveis na Web para ver 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 não especificado corresponde a todos os contextos disponíveis. Portanto, um filtro de `{}` 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
Tipo enumerado
"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 service worker.
"OFFSCREEN_DOCUMENT"
Especifica o tipo de contexto como um documento fora da tela.
"SIDE_PANEL"
Especifica o tipo de contexto como um painel lateral.
ExtensionContext
Um contexto que hospeda o conteúdo da extensão.
Propriedades
-
contextId
string
Um identificador exclusivo para esse contexto
-
contextType
O tipo de contexto a que isso corresponde.
-
documentId
string opcional
Um UUID para o documento associado a esse contexto ou "undefined" se o contexto não está hospedado em um documento.
-
documentOrigin
string opcional
A origem do documento associado a esse contexto ou "undefined" se o contexto não está hospedado em um documento.
-
documentUrl
string opcional
O URL do documento associado a esse contexto ou "undefined" se o contexto não está hospedado em um documento.
-
frameId
number
O ID do frame para o contexto, ou -1 se esse contexto não estiver hospedado em um frame.
-
navegação anônima
boolean
Se o contexto está associado a um perfil de navegação anônima.
-
tabId
number
O ID da guia para o contexto ou -1 se esse contexto não estiver hospedado em uma guia.
-
windowId
number
O ID da janela para este 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 ou mais recenteUm UUID do documento que abriu a conexão.
-
documentLifecycle
string opcional
Chrome 106 ou mais recenteO ciclo de vida em que o documento que abriu a conexão se encontra 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. Só será definido quando
tab
estiver definido. -
id
string opcional
O ID da extensão que abriu a conexão, se houver.
-
nativeApplication
string opcional
Chrome 74 ou mais recenteO nome do aplicativo nativo que abriu a conexão, se houver.
-
origem
string opcional
Chrome 80 ou mais recenteA origem da página ou do frame que abriu a conexão. Ele pode variar em relação à propriedade do URL (por exemplo, about:blank) ou opaco (por exemplo, iframes em sandbox). Isso é útil para identificar se a origem é confiável caso não seja possível identificar imediatamente a partir do URL.
-
.
Guia opcional
O
tabs.Tab
que abriu a conexão, se houver. Essa propriedade estará presente apenas 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 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, será o URL do iframe, não o URL da página que o hospeda.
OnInstalledReason
O motivo pelo qual esse evento está sendo despachado.
Tipo enumerado
"install"
especifica o motivo do evento como uma instalação.
"update"
especifica o motivo do evento como uma atualização de 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 para um módulo compartilhado.
OnRestartRequiredReason
O motivo pelo qual o evento está sendo despachado. "app_update" é usado quando a reinicialização é necessária porque o aplicativo está atualizado para uma versão mais recente. "os_update" é usado quando a reinicialização é necessária porque o navegador/SO está atualizado para uma versão mais recente. A opção "periódico" é usada quando o sistema é executado por mais tempo do que o tempo de atividade permitido definido na política corporativa.
Tipo enumerado
"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.
"periódico"
Especifica o motivo do evento como uma reinicialização periódica do app.
PlatformArch
A arquitetura do processador da máquina.
Tipo enumerado
"arm"
Especifica a arquitetura do operador 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 da arquitetura em algumas plataformas.
-
os
O sistema operacional em que o Chrome está sendo executado.
PlatformNaclArch
A arquitetura do cliente nativo. Isso pode ser diferente da arquitetura em algumas plataformas.
Tipo enumerado
"arm"
Especifica a arquitetura nativa do cliente 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 nativa do cliente como mips.
"mips64"
Especifica a arquitetura do cliente nativo como mips64.
PlatformOs
O sistema operacional em que o Chrome está sendo executado.
Tipo enumerado
"mac"
Especifica o sistema operacional MacOS.
"win"
especifica o sistema operacional Windows.
"android"
especifica o sistema operacional Android.
"cros"
Especifica o sistema operacional do 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 mais informações em Conexões de longa duração.
Propriedades
-
nome
string
O nome da porta, conforme especificado na chamada para
runtime.connect
. -
onDisconnect
Evento<functionvoid>
Disparado quando a porta é desconectada das outras extremidades.
runtime.lastError
poderá ser definido se a porta tiver sido desconectada por um erro. Se a porta for fechada por disconnect, esse evento será disparado apenas na outra extremidade. Este evento é disparado no máximo uma vez. Consulte também Ciclo de vida da porta.A função
onDisconnect.addListener
tem esta aparência:(callback: function) => {...}
-
onMessage
Evento<functionvoid>
Este evento é disparado quando postMessage é chamado pela outra extremidade da porta.
A função
onMessage.addListener
tem esta aparência:(callback: function) => {...}
-
remetente
MessageSender opcional
Essa propriedade só vai estar presente nas portas transmitidas para 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
tem esta aparência:() => {...}
-
postMessage
void
Envie uma mensagem para a outra extremidade da porta. Se a porta estiver desconectada, será gerado um erro.
A função
postMessage
tem esta aparência:(message: any) => {...}
-
mensagem
qualquer um
Chrome 52 ou mais recenteA mensagem a ser enviada. Este objeto deve ser compatível com JSON.
-
RequestUpdateCheckStatus
Resultado da verificação de atualização.
Tipo enumerado
"Limitaçãod"
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 instalar.
"update_available"
Especifica que há uma atualização disponível para instalação.
Propriedades
id
O ID da extensão/aplicativo.
Tipo
string
lastError
Preenchido com uma mensagem de erro se a chamada de uma função de API falhar. Caso contrário, o valor será indefinido. Isso só é definido no escopo do callback dessa função. Se um erro for produzido, mas o 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,
)
Tentativas de conectar listeners em uma extensão (como a página de segundo plano) ou 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 na Web. Ele 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 o tabs.connect
.
Parâmetros
-
extensionId
string opcional
O ID da extensão a ser conectada. Se omitido, será feita uma tentativa de conexão com sua própria extensão. Obrigatório se você enviar mensagens de uma página da Web para mensagens na Web.
-
connectInfo
objeto opcional
-
includeTlsChannelId
booleano opcional
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 em que as mensagens podem ser enviadas e recebidas. O evento onDisconnect da porta será disparado 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 requer a permissão "nativeMessaging"
. Consulte Mensagens nativas para mais informações.
Parâmetros
-
aplicativo
string
O nome do aplicativo registrado para se conectar.
Retorna
-
Porta em que as mensagens podem ser enviadas e recebidas com o aplicativo
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Recupera o objeto JavaScript "window" para a página de fundo executada dentro da extensão/aplicativo atual. Se a página de segundo plano for uma página de evento, o sistema garantirá que ela seja carregada antes de chamar o retorno de chamada. Se não houver uma página de fundo, um erro será definido.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(backgroundPage?: Window) => void
-
backgroundPage
Janela opcional
O objeto JavaScript "window" para a página de plano de fundo.
-
Retorna
-
Promise<Window | undefined>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Busca informações sobre contextos ativos associados a esta extensão
Parâmetros
-
filtro
Um filtro para encontrar contextos correspondentes. Um contexto corresponde se todos os campos especificados no filtro são correspondentes. Qualquer campo não especificado no filtro corresponde a todos os contextos.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(contexts: ExtensionContext[]) => void
-
contexts
Os contextos correspondentes, se houver.
-
Retorna
-
Promise<ExtensionContext[]>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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 DirectoryEntry para o diretório do pacote.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Retorna
-
Promise<DirectoryEntry>
Chrome 122 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Retorna informações sobre a plataforma atual.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Retorna
-
Promise<PlatformInfo>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getURL()
chrome.runtime.getURL(
path: string,
)
Converte um caminho relativo dentro de um diretório de instalação de app/extensão em um URL totalmente qualificado.
Parâmetros
-
caminho
string
Um caminho para um recurso dentro de um app/extensão expresso em relação ao diretório de instalação.
Retorna
-
string
O URL totalmente qualificado do 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](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
ou [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
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 apenas focar em uma página de opções aberta. Isso nunca fará com que a página do autor da chamada seja recarregada.
Se a extensão não declarar uma página de opções ou se o Chrome não tiver criado uma por algum outro motivo, o callback vai definir lastError
.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
reload()
chrome.runtime.reload()
Recarrega o app ou a extensão. Este 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 uma verificação imediata de atualização para este app/extensão.
Importante: a maioria das extensões/apps não deve usar esse método, já que o Chrome já faz verificações automáticas em intervalos de algumas horas, e você pode ouvir o evento runtime.onUpdateAvailable
sem precisar chamar requestUpdateCheck.
Esse método só é apropriado para chamadas em circunstâncias muito limitadas, como se sua extensão se comunicar com um serviço de back-end e o serviço de back-end determinou que a versão da extensão do cliente está muito desatualizada e você gostaria de solicitar a um usuário que faça a atualização. A maioria dos outros usos de requestUpdateCheck, como chamá-lo incondicionalmente com base em um timer repetido, provavelmente serve apenas para desperdiçar recursos do cliente, da rede e do servidor.
Observação: quando chamada com um retorno de chamada, em vez de retornar um objeto, essa função retornará as duas propriedades como argumentos separados passados para o retorno de chamada.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: object) => void
-
resultado
objeto
Chrome 109 ou mais recenteObjeto RequestUpdateCheckResult que contém o status da verificação de atualizações e todos os detalhes do resultado, se houver uma atualização disponível.
-
status
Resultado da verificação de atualização.
-
versão
string opcional
Se uma atualização estiver disponível, ele contém a versão dela.
-
-
Retorna
-
Promise<object>
Chrome 109 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
restart()
chrome.runtime.restart()
Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque. Caso contrário, é um ambiente autônomo.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Reinicie o dispositivo ChromeOS quando o app for executado no modo quiosque após os segundos fornecidos. Se chamada novamente antes do término desse horário, a reinicialização será adiada. Se chamada com um valor de -1, a reinicialização será cancelada. É um ambiente autônomo em modo não quiosque. Ele só pode ser chamado repetidamente pela primeira extensão para invocar essa API.
Parâmetros
-
segundos
number
Tempo de espera em segundos antes de reiniciar o dispositivo ou -1 para cancelar uma reinicialização programada.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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/app diferente. Semelhante ao runtime.connect
, mas envia apenas uma mensagem, com uma resposta opcional. Ao enviar para sua extensão, o evento runtime.onMessage
será disparado em todos os frames da extensão (exceto o frame do remetente) ou runtime.onMessageExternal
se for uma extensão diferente. As extensões não podem enviar mensagens a 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 onde enviar a mensagem. Se omitido, a mensagem será enviada para seu próprio aplicativo/extensão. Obrigatório se enviar mensagens de uma página da Web para mensagens na Web.
-
mensagem
qualquer um
A mensagem a ser enviada. Essa mensagem deve ser um objeto compatível com JSON.
-
do modelo.
objeto opcional
-
includeTlsChannelId
booleano opcional
Se o ID do canal TLS será transmitido para onMessageExternal para processos que estão detectando o evento de conexão.
-
-
callback
função optional
Chrome 99 ou mais recenteO parâmetro
callback
tem esta aparência:(response: any) => void
-
resposta
qualquer um
O objeto de resposta JSON enviado pelo gerenciador da mensagem. Se ocorrer um erro durante a conexão com a extensão, o callback será chamado sem argumentos, e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Prometa<qualquer>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Enviar uma única mensagem para um app nativo. Esse método requer a permissão "nativeMessaging"
.
Parâmetros
-
aplicativo
string
O nome do host de mensagens nativas.
-
mensagem
objeto
A mensagem que será transmitida para o host de mensagens nativas.
-
callback
função optional
Chrome 99 ou mais recenteO parâmetro
callback
tem esta aparência:(response: any) => void
-
resposta
qualquer um
A mensagem de resposta enviada pelo host de mensagens nativas. Se ocorrer um erro durante a conexão com o host de mensagens nativas, o callback será chamado sem argumentos, e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Prometa<qualquer>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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, realizar análises e implementar pesquisas. Máximo de 1.023 caracteres.
Parâmetros
-
url
string
URL que será aberto após a desinstalação da extensão. Esse URL deve ter um esquema http: ou https:. Defina uma string vazia para não abrir uma nova guia após a desinstalação.
-
callback
função optional
Chrome 45 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 99 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
Eventos
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Use runtime.onRestartRequired
.
Disparado quando uma atualização do Chrome está disponível, mas não é instalado imediatamente porque é necessário reiniciar o navegador.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
Disparado quando uma conexão é feita por um processo de extensão ou um script de conteúdo (por runtime.connect
).
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
Disparado quando uma conexão é feita de outra extensão (por runtime.connect
) ou de um site conectável externamente.
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Disparado quando uma conexão é feita de um aplicativo nativo. Este evento requer a permissão "nativeMessaging"
. Ela só é compatível com o Chrome OS.
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
Disparado 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 esta aparência:(details: object) => void
-
detalhes
objeto
-
id
string opcional
Indica o ID da extensão do módulo compartilhado importada que foi atualizada. Só estará presente se o "motivo" for "shared_module_update".
-
previousVersion
string opcional
Indica a versão anterior da extensão, que acabou de ser atualizada. Só estará presente se o "motivo" for "atualização".
-
reason
O motivo pelo qual esse evento está sendo despachado.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Disparado quando uma mensagem é enviada de um processo de extensão (por runtime.sendMessage
) ou um script de conteúdo (por tabs.sendMessage
).
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem esta aparência:() => void
-
retorna
booleano | indefinido
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
Disparado quando uma mensagem é enviada de outra extensão (por runtime.sendMessage
). Não pode ser usada em um script de conteúdo.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem esta aparência:() => void
-
retorna
booleano | indefinido
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Disparado quando um app ou dispositivo em que ele é executado precisa ser reiniciado. O app precisa fechar todas as janelas no momento mais conveniente para permitir 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, o evento só é disparado para aplicativos de quiosque do Chrome OS.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(reason: OnRestartRequiredReason) => void
-
reason
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Disparado quando um perfil com essa extensão instalada é iniciado pela primeira vez. Este evento não é disparado quando um perfil de navegação anônima é iniciado, mesmo que a extensão esteja operando no modo de navegação anônima "dividido".
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:() => 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 descarregada, não há garantia de que todas as operações assíncronas iniciadas durante o processamento desse evento serão concluídas. Se mais atividades na página do evento ocorrerem antes dela ser descarregada, o evento onSuspendCanceled será enviado, e a página não será descarregada.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
Enviado após onSuspend para indicar que o app não será descarregado.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
Disparado quando uma atualização está disponível, mas não é instalada imediatamente porque o app está em execução no momento. Se você não fizer nada, a atualização será instalada na próxima vez que a página de segundo plano for descarregada. Se quiser uma instalação mais cedo, chame chrome.runtime.reload() explicitamente. Se a sua extensão usar uma página de segundo plano persistente, a página de fundo 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 vez que o próprio Chrome seja instalado. Se nenhum manipulador estiver detectando esse evento e sua extensão tiver uma página persistente em segundo plano, ele se comportará como se chrome.runtime.reload() fosse chamado em resposta a esse evento.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(details: object) => void
-
detalhes
objeto
-
versão
string
O número da versão da atualização disponível.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Disparado quando uma conexão é feita a partir de um script de usuário a partir desta extensão.
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
Disparado quando uma mensagem é enviada de um script de usuário associado à mesma extensão.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensagem
qualquer um
-
remetente
-
sendResponse
função
O parâmetro
sendResponse
tem esta aparência:() => void
-
retorna
booleano | indefinido
-