Descripción
Usa la API de chrome.runtime
para recuperar el service worker, mostrar detalles sobre el manifiesto, y detectar eventos en el ciclo de vida de la extensión y responder a ellos. También puedes usar esta API para convertir la ruta de acceso relativa de las URLs en URLs completamente calificadas.
La mayoría de los miembros de esta API no requieren ningún permiso. connectNative()
, sendNativeMessage()
y onNativeConnect
necesitan este permiso.
En el siguiente ejemplo, se muestra cómo declarar el permiso "nativeMessaging"
en el manifiesto:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Conceptos y uso
La API de Runtime proporciona métodos para admitir varias áreas en las que tus extensiones puede usar:
- Transmisión de mensajes
- La extensión puede comunicarse con diferentes contextos dentro de ella y también con otras extensiones mediante estos métodos y eventos:
connect()
,onConnect
,onConnectExternal
,sendMessage()
,onMessage
yonMessageExternal
. Además, tu extensión puede pasar mensajes a aplicaciones nativas del dispositivo del usuario usandoconnectNative()
ysendNativeMessage()
- Accede a los metadatos de extensiones y plataformas
- Estos métodos te permiten recuperar varios metadatos específicos sobre la extensión y el
plataforma. Los métodos de esta categoría incluyen
getManifest()
ygetPlatformInfo()
- Administra el ciclo de vida y las opciones de las extensiones
- Estas propiedades te permiten realizar algunas metaoperaciones en la extensión y mostrar la página de opciones.
Los métodos y eventos de esta categoría incluyen
onInstalled
:onStartup
,openOptionsPage()
,reload()
:requestUpdateCheck()
setUninstallURL()
. - Utilidades auxiliares
- Estos métodos son útiles, como la conversión de representaciones de recursos internos en
o en formatos externos. Los métodos de esta categoría incluyen
getURL()
- Utilidades del modo kiosco
- Estos métodos solo están disponibles en ChromeOS y existen principalmente para admitir implementaciones de kiosco.
Los métodos de esta categoría incluyen
restart()
yrestartAfterDelay()
.
Comportamiento de la extensión sin empaquetar
Cuando una extensión desempaquetada se vuelve a cargar, se considera una actualización. Esto significa que el
Se activará el evento chrome.runtime.onInstalled
con el motivo "update"
. Esta
Incluye cuando la extensión se vuelve a cargar con chrome.runtime.reload()
.
Casos de uso
Agrega una imagen a una página web
Para que una página web acceda a un recurso alojado en otro dominio, debe especificar la URL completa del recurso
(p.ej., <img src="https://example.com/logo.png">
). Lo mismo sucede cuando se incluye un recurso de extensión en
una página web. Las dos diferencias son que los recursos de la extensión se deben exponer como
accesibles y que, por lo general, las secuencias de comandos de contenido son responsables de inyectar
recursos de extensión.
En este ejemplo, la extensión agregará logo.png
a la página donde el contenido
de Terraform se inyecta usando runtime.getURL()
para crear un
completamente calificada. Pero, primero, el recurso debe declararse como un recurso accesible desde la Web en el manifiesto.
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);
}
Envía datos de una secuencia de comandos de contenido al service worker
Es común que las secuencias de comandos de contenido de una extensión necesiten datos administrados por otra parte de la extensión. como el service worker. Al igual que dos ventanas del navegador abiertas en la misma página web, estas dos contextos no pueden acceder directamente a los valores de otro. En su lugar, la extensión puede usar message pasar para coordinar entre estos contextos diferentes.
En este ejemplo, la secuencia de comandos de contenido necesita algunos datos del service worker de la extensión para
inicializamos su IU. Para obtener estos datos, pasa el mensaje get-user-data
definido por el desarrollador.
al service worker, que responde con una copia de la información del usuario.
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);
}
});
Cómo recopilar comentarios sobre las desinstalaciones
Muchas extensiones usan encuestas posteriores a la desinstalación para comprender cómo podrían funcionar mejor. y mejorar la retención. En el siguiente ejemplo, se muestra cómo agregar esta funcionalidad.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
Ejemplos
Consulta la demostración de Manifest V3: Recursos accesibles para la Web para obtener más ejemplos de la API de Runtime.
Tipos
ContextFilter
Un filtro que debe coincidir con ciertos contextos de extensiones. Los contextos coincidentes deben coincidir con todos los filtros especificados. Cualquier filtro que no se especifique coincidirá con todos los contextos disponibles. Por lo tanto, un filtro de `{}` coincidirá con todos los contextos disponibles.
Propiedades
-
contextIds
string[] opcional
-
contextTypes
ContextType[] opcional
-
documentIds
string[] opcional
-
documentOrigins
string[] opcional
-
documentUrls
string[] opcional
-
frameIds
number[] opcional
-
incógnito
booleano opcional
-
tabIds
number[] opcional
-
windowIds
number[] opcional
ContextType
Enum
"TAB"
Especifica el tipo de contexto como una pestaña
"POPUP"
Especifica el tipo de contexto como una ventana emergente de extensión
"BACKGROUND"
Especifica el tipo de contexto como un service worker.
"OFFSCREEN_DOCUMENT"
Especifica el tipo de contexto como un documento fuera de pantalla.
"SIDE_PANEL"
Especifica el tipo de contexto como panel lateral.
ExtensionContext
Un contexto que aloja contenido de extensión.
Propiedades
-
ID de contexto
string
Un identificador único para este contexto
-
contextType
Es el tipo de contexto al que corresponde.
-
documentId
string opcional
Es un UUID para el documento asociado con este contexto, o no definido si este contexto no está alojado en un documento.
-
documentOrigin
string opcional
El origen del documento asociado con este contexto, o indefinido si el contexto no está alojado en un documento.
-
documentUrl
string opcional
Es la URL del documento asociado a este contexto, o no definida si el contexto no está alojado en un documento.
-
frameId
número
El ID del marco para este contexto, o -1 si este contexto no está alojado en un marco.
-
incógnito
boolean
Si el contexto está asociado con un perfil de incógnito.
-
tabId
número
El ID de la pestaña para este contexto o -1 si este contexto no está alojado en una pestaña.
-
windowId
número
El ID de la ventana para este contexto, o -1 si este contexto no está alojado en una ventana.
MessageSender
Un objeto que contiene información sobre el contexto de la secuencia de comandos que envió un mensaje o una solicitud.
Propiedades
-
documentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento que abrió la conexión.
-
documentLifecycle
string opcional
Chrome 106 y versiones posterioresEl ciclo de vida en el que se encontraba el documento que abrió la conexión en el momento en que se creó el puerto. Ten en cuenta que el estado del ciclo de vida del documento puede haber cambiado desde la creación del puerto.
-
frameId
número opcional
El marco que abrió la conexión. 0 para los fotogramas de nivel superior, positivo para los fotogramas secundarios Esto solo se establecerá cuando se establezca
tab
. -
id
string opcional
El ID de la extensión que abrió la conexión, si corresponde.
-
nativeApplication
string opcional
Chrome 74 y versiones posterioresEl nombre de la aplicación nativa que abrió la conexión, si corresponde.
-
origin
string opcional
Chrome 80 y versiones posterioresEl origen de la página o el marco que abrió la conexión. Puede variar de la propiedad de la URL (p.ej., about:blank) o ser opaca (p.ej., iframes de zona de pruebas). Esto es útil para identificar si el origen es confiable en caso de que no se sepa inmediatamente a partir de la URL.
-
tab
Pestaña opcional
El
tabs.Tab
que abrió la conexión, si lo hay. Esta propiedad solo estará presente cuando se abra la conexión desde una pestaña (incluidas las secuencias de comandos de contenido) y solo si la app receptora es una extensión, no una app. -
tlsChannelId
string opcional
El ID del canal TLS de la página o el marco que abrió la conexión, si la extensión lo solicita y si está disponible.
-
url
string opcional
La URL de la página o el marco que abrió la conexión. Si el remitente está en un iframe, será la URL del iframe, no la URL de la página que lo aloja.
OnInstalledReason
El motivo por el que se despacha este evento.
Enum
"install"
Especifica el motivo del evento como una instalación.
"update"
Especifica el motivo del evento como una actualización de la extensión.
"chrome_update"
Especifica el motivo del evento como una actualización de Chrome.
"shared_module_update"
Especifica el motivo del evento como una actualización de un módulo compartido.
OnRestartRequiredReason
El motivo por el que se despacha el evento. "app_update" se usa cuando es necesario reiniciar porque la aplicación se actualiza a una versión más reciente. "os_update" se usa cuando es necesario reiniciar porque el navegador o el SO están actualizados a una versión más reciente. 'periódico' se usa cuando el sistema se ejecuta por un período superior al establecido en la política empresarial.
Enum
"app_update"
Especifica el motivo del evento como una actualización de la app.
"os_update"
Especifica el motivo del evento como una actualización del sistema operativo.
"periodic"
Especifica el motivo del evento como un reinicio periódico de la app.
PlatformArch
La arquitectura del procesador de la máquina.
Enum
"arm"
Especifica la arquitectura del procesador como arm.
"arm64"
Especifica la arquitectura del procesador como arm64.
"x86-32"
Especifica la arquitectura del procesador como x86-32.
"x86-64"
Especifica la arquitectura del procesador como x86-64.
"mips"
Especifica la arquitectura del procesador como mips.
"mips64"
Especifica la arquitectura del procesador como mips64.
PlatformInfo
Es un objeto que contiene información sobre la plataforma actual.
Propiedades
-
arch
La arquitectura del procesador de la máquina.
-
nacl_arch
La arquitectura nativa del cliente Esto puede ser diferente de la arquitectura en algunas plataformas.
-
os
El sistema operativo en el que se ejecuta Chrome.
PlatformNaclArch
La arquitectura nativa del cliente Esto puede ser diferente de la arquitectura en algunas plataformas.
Enum
"arm"
Especifica la arquitectura nativa del cliente como arm.
"x86-32"
Especifica la arquitectura nativa del cliente como x86-32.
"x86-64"
Especifica la arquitectura del cliente nativo como x86-64.
"mips"
Especifica la arquitectura del cliente nativo como mips.
"mips64"
Especifica la arquitectura del cliente nativo como mips64.
PlatformOs
El sistema operativo en el que se ejecuta Chrome.
Enum
"mac"
Especifica el sistema operativo MacOS.
"win"
Especifica el sistema operativo Windows.
"android"
Especifica el sistema operativo Android.
"cros"
Especifica el sistema operativo Chrome.
"linux"
Especifica el sistema operativo Linux.
"openbsd"
Especifica el sistema operativo OpenBSD.
"fuchsia"
Especifica el sistema operativo Fuchsia.
Port
Es un objeto que permite una comunicación bidireccional con otras páginas. Para obtener más información, consulta Conexiones de larga duración.
Propiedades
-
nombre
string
Es el nombre del puerto, como se especifica en la llamada a
runtime.connect
. -
onDisconnect
Evento<functionvoidvoid>
Se activa cuando el puerto se desconecta del otro extremo. Es posible que se configure
runtime.lastError
si el puerto se desconectó por un error. Si el puerto se cierra mediante la opción desconnect, este evento solo se activa en el otro extremo. Este evento se activa como máximo una vez (consulta también Duración del puerto).La función
onDisconnect.addListener
se ve de la siguiente manera:(callback: function) => {...}
-
onMessage
Evento<functionvoidvoid>
Este evento se activa cuando el otro extremo del puerto llama a postMessage.
La función
onMessage.addListener
se ve de la siguiente manera:(callback: function) => {...}
-
remitente
MessageSender opcional
Esta propiedad solo estará presente en los puertos que se pasen a los objetos de escucha onConnect / onConnectExternal / onConnectNative.
-
desconectar
void
Desconecta el puerto de inmediato. Llamar a
disconnect()
en un puerto ya desconectado no tiene ningún efecto. Cuando se desconecta un puerto, no se enviarán eventos nuevos a este.La función
disconnect
se ve de la siguiente manera:() => {...}
-
postMessage
void
Envía un mensaje al otro extremo del puerto. Si el puerto está desconectado, se genera un error.
La función
postMessage
se ve de la siguiente manera:(message: any) => {...}
-
mensaje
cualquiera
Chrome 52 y versiones posterioresEl mensaje que se enviará. Este objeto debe ser JSON.
-
RequestUpdateCheckStatus
Resultado de la búsqueda de actualizaciones.
Enum
"throttled"
Especifica que se limitó la verificación de estado. Esto puede ocurrir después de comprobaciones repetidas en un período breve.
"no_update"
Especifica que no hay actualizaciones disponibles para instalar.
"update_available"
Especifica que hay una actualización disponible para instalar.
Propiedades
id
Es el ID de la extensión o la app.
Tipo
string
lastError
Se propaga con un mensaje de error si falla la llamada a una función de API. de lo contrario, indefinido. Esto solo se define dentro del alcance de la devolución de llamada de esa función. Si se produce un error, pero no se accede a runtime.lastError
dentro de la devolución de llamada, se registra un mensaje en la consola en el que se indica la función de la API que produjo el error. Las funciones de la API que muestran promesas no configuran esta propiedad.
Tipo
objeto
Propiedades
-
mensaje
string opcional
Detalles sobre el error que se produjo.
Métodos
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
Intenta conectar objetos de escucha dentro de una extensión (como la página en segundo plano) u otras extensiones o apps. Esto es útil para las secuencias de comandos de contenido que se conectan a sus procesos de extensiones, la comunicación entre apps o extensiones y los mensajes web. Ten en cuenta que esto no se conecta con ningún objeto de escucha en una secuencia de comandos de contenido. Las extensiones pueden conectarse a las secuencias de comandos de contenido incorporadas en las pestañas a través de tabs.connect
.
Parámetros
-
extensionId
string opcional
El ID de la extensión a la que se conectará. Si se omite, se intentará establecer una conexión con su propia extensión. Obligatorio si se envían mensajes desde una página web para mensajería web.
-
connectInfo
objeto opcional
-
includeTlsChannelId
booleano opcional
Indica si el ID del canal de TLS se pasará a onConnectExternal para los procesos que escuchan el evento de conexión.
-
nombre
string opcional
Se pasará a onConnect para los procesos que escuchen el evento de conexión.
-
Muestra
-
Puerto a través del cual se pueden enviar y recibir mensajes. El evento onDisconnect del puerto se activa si la extensión no existe.
connectNative()
chrome.runtime.connectNative(
application: string,
)
Se conecta a una aplicación nativa en la máquina anfitrión. Este método requiere el permiso "nativeMessaging"
. Consulta Mensajería nativa para obtener más información.
Parámetros
-
aplicación
string
El nombre de la aplicación registrada a la que te conectarás.
Muestra
-
Puerto a través del cual se pueden enviar y recibir mensajes con la aplicación
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Recupera la "ventana" de JavaScript. objeto de la página en segundo plano que se ejecuta dentro de la extensión o aplicación actual. Si la página en segundo plano es una página de evento, el sistema se asegurará de que se cargue antes de llamar a la devolución de llamada. Si no hay una página en segundo plano, se establece un error.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(backgroundPage?: Window) => void
-
backgroundPage
Ventana opcional
La "ventana" de JavaScript de la página en segundo plano.
-
Muestra
-
Promise<Window | indefinido>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Recupera información sobre los contextos activos asociados con esta extensión
Parámetros
-
filter
Un filtro para encontrar contextos coincidentes. Un contexto coincide si concuerda con todos los campos especificados en el filtro. Cualquier campo sin especificar en el filtro coincide con todos los contextos.
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(contexts: ExtensionContext[]) => void
-
contextos
Los contextos coincidentes, si los hubiera.
-
Muestra
-
Promise<ExtensionContext[]>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getManifest()
chrome.runtime.getManifest()
Muestra detalles sobre la app o extensión del manifiesto. El objeto que se muestra es una serialización del archivo de manifiesto completo.
Muestra
-
objeto
Los detalles del manifiesto
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
Muestra una DirectoryEntry para el directorio del paquete.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Muestra
-
Promise<DirectoryEntry>
Chrome 122 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Muestra información sobre la plataforma actual.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Muestra
-
Promise<PlatformInfo>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getURL()
chrome.runtime.getURL(
path: string,
)
Convierte una ruta de acceso relativa dentro de un directorio de instalación de app/extensión en una URL completamente calificada.
Parámetros
-
ruta de acceso
string
Una ruta de acceso a un recurso dentro de una app o extensión expresada en relación con su directorio de instalación.
Muestra
-
string
Es la URL completamente calificada al recurso.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
Si es posible, abre la página de opciones de tu extensión.
El comportamiento preciso puede depender de la clave [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)
de tu manifiesto, o de lo que Chrome admite en ese momento. Por ejemplo, es posible que la página se abra en una pestaña nueva, en chrome://extensions, en una aplicación o en una página de opciones abierta. Nunca hará que se vuelva a cargar la página del llamador.
Si la extensión no declara una página de opciones o Chrome no pudo crear una por algún otro motivo, la devolución de llamada establecerá el valor lastError
.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
reload()
chrome.runtime.reload()
Vuelve a cargar la app o extensión. Este método no se admite en el modo kiosco. Para el modo kiosco, usa el método chrome.runtime.restart().
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
Solicita que se realice una verificación inmediata de actualizaciones de esta aplicación o extensión.
Importante: La mayoría de las extensiones o apps no deben usar este método, ya que Chrome ya realiza verificaciones automáticas cada pocas horas, y puedes escuchar el evento runtime.onUpdateAvailable
sin necesidad de llamar a requestUpdateCheck.
Este método solo es apropiado para realizar llamadas en circunstancias muy limitadas, por ejemplo, si tu extensión se comunica con un servicio de backend y el servicio de backend determinó que la versión de la extensión de cliente está muy desactualizada y quieres indicarle a un usuario que la actualice. La mayoría de los otros usos de requestUpdateCheck, como la llamada incondicional en función de un temporizador recurrente, probablemente solo sirvan para desperdiciar recursos de clientes, redes y servidores.
Nota: Cuando se realiza una llamada con una devolución de llamada, en lugar de mostrar un objeto, esta función muestra las dos propiedades como argumentos separados pasados a la devolución de llamada.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(result: object) => void
-
resultado
objeto
Chrome 109 y versiones posterioresUn objeto RequestUpdateCheckResult que contiene el estado de la verificación de actualizaciones y cualquier detalle del resultado si hay una actualización disponible.
-
estado
Resultado de la búsqueda de actualizaciones.
-
versión
string opcional
Si hay una actualización disponible, contiene la versión de la actualización disponible.
-
-
Muestra
-
Promise<object>
Chrome 109 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
restart()
chrome.runtime.restart()
Reinicia el dispositivo ChromeOS cuando la app se ejecute en modo kiosco. De lo contrario, es no-op.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Reinicia el dispositivo ChromeOS cuando la app se ejecute en modo kiosco después de unos segundos determinados. Si se vuelve a llamar antes de que finalice el tiempo, se retrasará el reinicio. Si se llama con un valor de -1, se cancelará el reinicio. Es una no-op que no está en modo kiosco. Solo la primera extensión puede llamarla repetidamente en invocar esta API.
Parámetros
-
segundos
número
Tiempo de espera en segundos antes de reiniciar el dispositivo o -1 para cancelar un reinicio programado.
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Envía un único mensaje a los objetos de escucha de eventos de tu extensión o de una extensión o app diferente. Es similar a runtime.connect
, pero solo envía un mensaje con una respuesta opcional. Si envías el evento a tu extensión, se activará el evento runtime.onMessage
en cada marco de tu extensión (excepto en el marco del remitente) o runtime.onMessageExternal
, si es una extensión diferente. Ten en cuenta que las extensiones no pueden enviar mensajes a las secuencias de comandos de contenido con este método. Para enviar mensajes a las secuencias de comandos de contenido, usa tabs.sendMessage
.
Parámetros
-
extensionId
string opcional
El ID de la extensión a la que se enviará el mensaje. Si se omite, el mensaje se enviará a tu propia extensión o app. Obligatorio si se envían mensajes desde una página web para mensajería web.
-
mensaje
cualquiera
El mensaje que se enviará. Este mensaje debe ser un objeto que admita JSON.
-
opciones
objeto opcional
-
includeTlsChannelId
booleano opcional
Indica si el ID del canal de TLS se pasará a onMessageExternal para los procesos que escuchan el evento de conexión.
-
-
callback
función opcional
Chrome 99 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:(response: any) => void
-
respuesta
cualquiera
El objeto de respuesta JSON que envía el controlador del mensaje. Si se produce un error durante la conexión a la extensión, se llamará a la devolución de llamada sin argumentos y
runtime.lastError
se establecerá en el mensaje de error.
-
Muestra
-
Promesa<cualquiera>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Envía un solo mensaje a una aplicación nativa. Este método requiere el permiso "nativeMessaging"
.
Parámetros
-
aplicación
string
El nombre del host de mensajería nativa.
-
mensaje
objeto
El mensaje que se transmitirá al host de mensajería nativa.
-
callback
función opcional
Chrome 99 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:(response: any) => void
-
respuesta
cualquiera
El mensaje de respuesta que envía el host de mensajería nativa. Si se produce un error durante la conexión al host de mensajería nativa, se llamará a la devolución de llamada sin argumentos y
runtime.lastError
se establecerá en el mensaje de error.
-
Muestra
-
Promesa<cualquiera>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
Establece la URL que se visitará tras la desinstalación. Se puede usar para limpiar datos del servidor, realizar estadísticas e implementar encuestas. Se admiten hasta 1,023 caracteres.
Parámetros
-
url
string
URL que se abrirá después de desinstalar la extensión. La URL debe tener un esquema http: o https:. Establece una cadena vacía para no abrir una pestaña nueva tras la desinstalación.
-
callback
función opcional
Chrome 45 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 99 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
Eventos
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Usa runtime.onRestartRequired
.
Se activa cuando hay una actualización de Chrome disponible, pero no se instala inmediatamente porque es necesario reiniciar el navegador.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
Se activa cuando se establece una conexión desde un proceso de extensión o una secuencia de comandos de contenido (de runtime.connect
).
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(port: Port) => void
-
puerto
-
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
Se activa cuando se establece una conexión desde otra extensión (de runtime.connect
) o desde un sitio web que se pueda conectar de forma externa.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(port: Port) => void
-
puerto
-
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Se activa cuando se establece una conexión desde una aplicación nativa. Este evento requiere el permiso "nativeMessaging"
. Solo es compatible con ChromeOS.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(port: Port) => void
-
puerto
-
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
Se activa cuando la extensión se instala por primera vez, cuando se actualiza a una nueva versión y cuando Chrome se actualiza a una nueva versión.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
id
string opcional
Indica el ID de la extensión importada del módulo compartido que se actualizó. Aparece solo si hay un "motivo". es 'shared_module_update'.
-
previousVersion
string opcional
Indica la versión anterior de la extensión, que se acaba de actualizar. Aparece solo si hay un "motivo". es "update".
-
Reason
El motivo por el que se despacha este evento.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Se activa cuando se envía un mensaje desde un proceso de extensión (de runtime.sendMessage
) o una secuencia de comandos de contenido (de tabs.sendMessage
).
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensaje
cualquiera
-
remitente
-
sendResponse
función
El parámetro
sendResponse
se ve de la siguiente manera:() => void
-
muestra
boolean | indefinido
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
Se activa cuando runtime.sendMessage
envía un mensaje desde otra extensión. No se puede utilizar en una secuencia de comandos de contenido.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensaje
cualquiera
-
remitente
-
sendResponse
función
El parámetro
sendResponse
se ve de la siguiente manera:() => void
-
muestra
boolean | indefinido
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Se activa cuando una app o el dispositivo en el que se ejecuta deben reiniciarse. La app debería cerrar todas las ventanas lo antes posible para permitir que se reinicie. Si la app no realiza ninguna acción, se aplicará de manera forzosa un reinicio después de transcurrido un período de gracia de 24 horas. Actualmente, este evento solo se activa para las aplicaciones de kiosco del Sistema operativo Chrome.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(reason: OnRestartRequiredReason) => void
-
Reason
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Se activa cuando se inicia un perfil que tiene esta extensión instalada por primera vez. Este evento no se activa cuando se inicia un perfil de incógnito, incluso si esta extensión opera en “split” modo Incógnito.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
Se envía a la página del evento justo antes de que se descargue. Esto le da a la extensión la oportunidad de realizar una limpieza. Ten en cuenta que, como la página se está descargando, no se garantiza que se complete ninguna operación asíncrona iniciada mientras se controla este evento. Si hay más actividad en la página del evento antes de que se descargue, se enviará el evento onSuspendCanceled y no se descargará la página.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
Se envía después de onSuspend para indicar que no se descargará la app después de todo.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
Se activa cuando hay una actualización disponible, pero no se instala inmediatamente porque la app se está ejecutando. Si no haces nada, la actualización se instalará la próxima vez que se descargue la página en segundo plano. Si deseas que se instale antes, puedes llamar explícitamente a chrome.runtime.reload(). Si tu extensión utiliza una página en segundo plano persistente, esta página nunca se descarga, por lo tanto, a menos que llames a chrome.runtime.reload() manualmente en respuesta a este evento, la actualización no se instalará hasta la próxima vez que se reinicie Chrome. Si no hay controladores que escuchen este evento y tu extensión tiene una página en segundo plano persistente, se comportará como si se llamara a chrome.runtime.reload() en respuesta a este evento.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
versión
string
El número de versión de la actualización disponible.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Se activa cuando se establece una conexión desde una secuencia de comandos de usuario desde esta extensión.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(port: Port) => void
-
puerto
-
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
Se activa cuando se envía un mensaje desde una secuencia de comandos de usuario asociada con la misma extensión.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
mensaje
cualquiera
-
remitente
-
sendResponse
función
El parámetro
sendResponse
se ve de la siguiente manera:() => void
-
muestra
boolean | indefinido
-