Descripción
Usa la API de chrome.webNavigation
para recibir notificaciones sobre el estado de las solicitudes de navegación en curso.
Permisos
webNavigation
Todos los métodos y eventos de chrome.webNavigation
requieren que declares el permiso "webNavigation"
en el manifiesto de la extensión. Por ejemplo:
{ "name": "My extension", ... "permissions": [
"webNavigation" ], ... }
Conceptos y uso
Orden de eventos
En el caso de una navegación que se completa correctamente, los eventos se activan en el siguiente orden:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
Cualquier error que se produzca durante el proceso generará un evento onErrorOccurred
. Para una navegación específica, no se activan más eventos después de onErrorOccurred
.
Si un frame de navegación contiene subframes, su onCommitted
se activa antes que el onBeforeNavigate
de cualquiera de sus elementos secundarios, mientras que onCompleted
se activa después de que se activan todos los onCompleted
de sus elementos secundarios.
Si se cambia el fragmento de referencia de un fotograma, se activa un evento onReferenceFragmentUpdated
. Este evento se puede activar en cualquier momento después de onDOMContentLoaded
, incluso después de onCompleted
.
Si se usa la API de historial para modificar el estado de un frame (p.ej., con history.pushState()
), se activa un evento onHistoryStateUpdated
. Este evento se puede activar en cualquier momento después de onDOMContentLoaded
.
Si una navegación restableció una página desde la memoria caché atrás/adelante, no se activará el evento onDOMContentLoaded
. El evento no se activa porque el contenido ya se cargó cuando se visitó la página por primera vez.
Si se activó una navegación con Chrome Instant o Páginas instantáneas, se intercambia una página completamente cargada en la pestaña actual. En ese caso, se activa un evento onTabReplaced
.
Relación con los eventos de webRequest
No hay un orden definido entre los eventos de la API de webRequest y los eventos de la API de webNavigation. Es posible que aún se reciban eventos de webRequest para los marcos que ya iniciaron una nueva navegación, o que una navegación solo continúe después de que los recursos de red ya se hayan cargado por completo.
En general, los eventos de webNavigation están estrechamente relacionados con el estado de navegación que se muestra en la IU, mientras que los eventos de webRequest corresponden al estado de la pila de red, que generalmente es opaco para el usuario.
IDs de pestañas
No todas las pestañas de navegación corresponden a pestañas reales en la IU de Chrome, por ejemplo, una pestaña que se está renderizando previamente. No se puede acceder a estas pestañas con la API de Tabs ni solicitar información sobre ellas llamando a webNavigation.getFrame()
o webNavigation.getAllFrames()
. Una vez que se intercambia una pestaña de este tipo, se activa un evento onTabReplaced
y se puede acceder a ella a través de estas APIs.
Marcas de tiempo
Es importante tener en cuenta que algunas rarezas técnicas en el manejo de procesos distintos de Chrome por parte del SO pueden hacer que el reloj se desvíe entre el navegador y los procesos de extensión. Esto significa que solo se garantiza que la propiedad timeStamp
del evento WebNavigation
sea coherente de forma interna.timeStamp
Comparar un evento con otro te dará el desplazamiento correcto entre ellos, pero compararlos con la hora actual dentro de la extensión (con (new Date()).getTime()
, por ejemplo) podría dar resultados inesperados.
IDs de fotogramas
Los marcos dentro de una pestaña se pueden identificar por un ID de marco. El ID del marco principal siempre es 0, y el ID de los marcos secundarios es un número positivo. Una vez que se construye un documento en un frame, su ID de frame permanece constante durante el ciclo de vida del documento. A partir de Chrome 49, este ID también es constante durante la vida útil del iframe (en varias navegaciones).
Debido a la naturaleza de varios procesos de Chrome, una pestaña puede usar diferentes procesos para renderizar la fuente y el destino de una página web. Por lo tanto, si se produce una navegación en un proceso nuevo, es posible que recibas eventos de la página nueva y de la anterior hasta que se confirme la navegación nueva (es decir, hasta que se envíe el evento onCommitted
para el nuevo marco principal). En otras palabras, es posible tener más de una secuencia pendiente de eventos webNavigation con el mismo frameId
. Las secuencias se pueden distinguir por la clave processId
.
También ten en cuenta que, durante una carga provisional, el proceso puede cambiar varias veces. Esto sucede cuando la carga se redirecciona a otro sitio. En este caso, recibirás eventos onBeforeNavigate
y onErrorOccurred
repetidos hasta que recibas el evento onCommitted
final.
Otro concepto problemático con las extensiones es el ciclo de vida del fotograma. Un frame aloja un documento (que está asociado a una URL confirmada). El documento puede cambiar (por ejemplo, al navegar), pero el frameId no lo hará, por lo que es difícil asociar que algo sucedió en un documento específico solo con frameIds. Presentamos el concepto de documentId, que es un identificador único por documento. Si se navega por un iframe y se abre un documento nuevo, el identificador cambiará. Este campo es útil para determinar cuándo las páginas cambian su estado del ciclo de vida (entre prerrenderizado, activo y almacenado en caché) porque permanece igual.
Tipos y calificadores de transición
El evento webNavigation
onCommitted
tiene una propiedad transitionType
y una propiedad transitionQualifiers
. El tipo de transición es el mismo que se usa en la API de History, que describe cómo el navegador navegó a esta URL en particular. Además, se pueden devolver varios calificadores de transición que definen aún más la navegación.
Existen los siguientes calificadores de transición:
Calificador de transición | Descripción |
---|---|
"client_redirect" | Durante la navegación, se produjeron uno o más redireccionamientos causados por etiquetas de actualización meta o JavaScript en la página. |
"server_redirect" | Durante la navegación, se produjeron uno o más redireccionamientos causados por los encabezados HTTP enviados desde el servidor. |
"forward_back" | El usuario usó los botones Adelante o Atrás para iniciar la navegación. |
"from_address_bar" | El usuario inició la navegación desde la barra de direcciones (también conocida como Cuadro multifunción). |
Ejemplos
Para probar esta API, instala el ejemplo de la API de webNavigation del repositorio de chrome-extension-samples.
Tipos
TransitionQualifier
Enum
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
Causa de la navegación. Se usan los mismos tipos de transición que se definen en la API de History. Estos son los mismos tipos de transición que se definen en la API de History, excepto que se usa "start_page"
en lugar de "auto_toplevel"
(para la retrocompatibilidad).
Enum
"link"
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"generated"
"start_page"
"form_submit"
"reload"
"palabra clave"
"keyword_generated"
Métodos
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
): Promise<object[] | undefined>
Recupera información sobre todos los marcos de una pestaña determinada.
Parámetros
- detalles
objeto
Es información sobre la pestaña de la que se recuperarán todos los fotogramas.
- tabId
número
Es el ID de la pestaña.
-
Muestra
-
Promesa<object[] | undefined>
Chrome 93 y versiones posteriores
getFrame()
chrome.webNavigation.getFrame(
details: object,
): Promise<object | undefined>
Recupera información sobre el fotograma determinado. Un frame hace referencia a un <iframe> o un <frame> de una página web, y se identifica con un ID de pestaña y un ID de frame.
Parámetros
- detalles
objeto
Es la información sobre el fotograma del que se recuperará información.
- documentId
cadena opcional
Chrome 106 y versiones posterioresEs el UUID del documento. Si se proporcionan frameId o tabId, se validarán para que coincidan con el documento encontrado por el ID de documento proporcionado.
- frameId
número opcional
ID del iframe en la pestaña determinada.
- processId
número opcional
Obsoleto desde Chrome 49Ahora los marcos se identifican de forma única por su ID de pestaña y su ID de marco. Ya no se necesita el ID de proceso y, por lo tanto, se ignora.
Es el ID del proceso que ejecuta el renderizador para esta pestaña.
- tabId
número opcional
ID de la pestaña en la que se encuentra el iframe.
-
Muestra
-
Promise<object | undefined>
Chrome 93 y versiones posteriores
Eventos
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Se activa cuando está a punto de ocurrir una navegación.
Parámetros
-
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
-
objeto
- Chrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
-
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos para una pestaña y un proceso determinados.
- Chrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
-
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
-
número
ID del marco principal o
-1
si este es el marco principal. -
número
Obsoleto desde Chrome 50El processId ya no se establece para este evento, ya que el proceso que renderizará el documento resultante no se conoce hasta onCommit.
Es el valor de -1.
-
número
Es el ID de la pestaña en la que está a punto de ocurrir la navegación.
-
número
Es la hora en la que el navegador estaba a punto de iniciar la navegación, en milisegundos desde la época.
-
string
-
-
-
objeto opcional
-
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Se activa cuando se confirma una navegación. Es posible que el documento (y los recursos a los que hace referencia, como imágenes y subframes) aún se estén descargando, pero al menos se recibió parte del documento del servidor y el navegador decidió cambiar al documento nuevo.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la hora en la que se confirmó la navegación, expresada en milisegundos desde la época.
- transitionQualifiers
Es una lista de calificadores de transición.
- transitionType
Causa de la navegación.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Se activa cuando un documento, incluidos los recursos a los que hace referencia, se carga y se inicializa por completo.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la hora en la que terminó de cargarse el documento, en milisegundos desde la época.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Se activa cuando se crea una ventana nueva o una pestaña nueva en una ventana existente para alojar una navegación.
Parámetros
-
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
-
objeto
-
número
Es el ID del frame con sourceTabId en el que se activa la navegación. El 0 indica el fotograma principal.
-
número
Es el ID del proceso que ejecuta el renderizador para el fotograma fuente.
-
número
ID de la pestaña en la que se activa la navegación.
-
número
ID de la pestaña en la que se abre la URL
-
número
Es la hora en la que el navegador estaba a punto de crear una vista nueva, en milisegundos desde la época.
-
string
Es la URL que se abrirá en la ventana nueva.
-
-
-
objeto opcional
-
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Se activa cuando se construye por completo el DOM de la página, pero es posible que los recursos a los que se hace referencia no terminen de cargarse.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la hora en la que se construyó por completo el DOM de la página, en milisegundos desde la época.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Se activa cuando se produce un error y se aborta la navegación. Esto puede ocurrir si se produjo un error de red o si el usuario abortó la navegación.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- error
string
Es la descripción del error.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Obsoleto desde Chrome 50El valor de processId ya no se establece para este evento.
Es el valor de -1.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la fecha y hora en que ocurrió el error, en milisegundos desde la época.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Se activa cuando el historial del frame se actualizó a una URL nueva. Todos los eventos futuros de ese fotograma usarán la URL actualizada.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la hora en la que se confirmó la navegación, expresada en milisegundos desde la época.
- transitionQualifiers
Es una lista de calificadores de transición.
- transitionType
Causa de la navegación.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Se activa cuando se actualiza el fragmento de referencia de un fotograma. Todos los eventos futuros de ese fotograma usarán la URL actualizada.
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- documentId
string
Chrome 106 y versiones posterioresEs el UUID del documento cargado.
- documentLifecycleChrome 106 y versiones posteriores
Es el ciclo de vida en el que se encuentra el documento.
- frameId
número
El valor 0 indica que la navegación se produce en la ventana de contenido de la pestaña, mientras que un valor positivo indica que la navegación se produce en un subframe. Los IDs de fotogramas son únicos dentro de una pestaña.
- frameTypeChrome 106 y versiones posteriores
Es el tipo de marco en el que se produjo la navegación.
- parentDocumentId
cadena opcional
Chrome 106 y versiones posterioresEs un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.
- parentFrameId
número
Chrome 74 y versiones posterioresID del marco principal o
-1
si este es el marco principal. - processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
- tabId
número
Es el ID de la pestaña en la que se produce la navegación.
- timeStamp
número
Es la hora en la que se confirmó la navegación, expresada en milisegundos desde la época.
- transitionQualifiers
Es una lista de calificadores de transición.
- transitionType
Causa de la navegación.
- url
string
-
-
- filtros
objeto opcional
- url
Son las condiciones que debe cumplir la URL a la que se navega. Los campos "schemes" y "ports" de UrlFilter se ignoran para este evento.
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Se activa cuando el contenido de la pestaña se reemplaza por otra pestaña (generalmente, renderizada previamente).
Parámetros
- callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) =& gt;void
- detalles
objeto
- replacedTabId
número
ID de la pestaña que se reemplazó.
- tabId
número
ID de la pestaña que reemplazó a la anterior.
- timeStamp
número
Es la fecha y hora en que se produjo el reemplazo, en milisegundos desde la época.
-
-