Descripción
Usa la API de chrome.webNavigation para recibir notificaciones sobre el estado de las solicitudes de navegación en curso.
Permisos
webNavigationTodos los métodos y eventos de browser.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 los eventos
Para 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 genera un evento onErrorOccurred. Para una navegación específica, no se activan más eventos después de onErrorOccurred.
Si un marco de navegación contiene submarcos, su onCommitted se activa antes que cualquiera de los onBeforeNavigate de sus elementos secundarios, mientras que onCompleted se activa después de todos los onCompleted de sus elementos secundarios.
Si se cambia el fragmento de referencia de un marco, 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 marco (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 de la memoria caché atrás/adelante, no se activará el evento onDOMContentLoaded. El evento no se activa porque el contenido ya completó la carga cuando se visitó la página
por primera vez.
Si se activó una navegación con Chrome Instant o Instant Pages, 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 se sigan recibiendo eventos de webRequest para marcos que ya iniciaron una navegación nueva o que una navegación solo continúe después de que los recursos de red ya estén completamente cargados.
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 suele ser 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 esas pestañas con la API de pestañas ni puedes 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 anomalías técnicas en la forma en que el SO maneja los distintos procesos de Chrome pueden hacer que el reloj se desvíe entre el navegador y los procesos de las extensiones. Eso significa que solo se garantiza que la propiedad timeStamp de la propiedad timeStamp del evento WebNavigation sea coherente de forma interna. 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) puede dar resultados inesperados.
IDs de marcos
Los marcos dentro de una pestaña se pueden identificar con 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 marco, su ID de marco permanece constante durante la vida útil del documento. A partir de Chrome 49, este ID también es constante durante la vida útil del marco (en varias navegaciones).
Debido a la naturaleza de varios procesos de Chrome, una pestaña puede usar diferentes procesos para renderizar el origen
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, se envía el evento onCommitted para el marco principal nuevo). En otras palabras, es posible tener más de una secuencia pendiente de eventos de 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 un sitio diferente. En este caso, recibirás eventos onBeforeNavigate y onErrorOccurred repetidos hasta que recibas el evento onCommitted final.
Otro concepto que es problemático con las extensiones es el ciclo de vida del marco. Un marco aloja un documento (que está asociado con una URL confirmada). El documento puede cambiar (por ejemplo, navegando), pero el frameId no, 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 marco y se abre un documento nuevo, el identificador cambiará. Este campo es útil para determinar cuándo las páginas cambian su estado de ciclo de vida (entre renderización previa, activa o almacenada en caché) porque sigue siendo el mismo.
Tipos de transición y calificadores
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 llegó 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 JavaScript o etiquetas de actualización de metadatos en la página. |
| "server_redirect" | Durante la navegación, se produjeron uno o más redireccionamientos causados por encabezados HTTP enviados desde el servidor. |
| "forward_back" | El usuario usó el botón 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 desde el repositorio chrome-extension-samples.
Tipos
TransitionQualifier
Enum
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
Es la causa de la navegación. Se usan los mismos tipos de transición que se definen en la API de historial. Estos son los mismos tipos de transición que se definen en la API de historial, excepto que se usa "start_page" en lugar de "auto_toplevel" (para mantener la retrocompatibilidad).
Enum
"link"
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"generated"
"start_page"
"form_submit"
"reload"
"keyword"
"keyword_generated"
Métodos
getAllFrames()
browser.webNavigation.getAllFrames(
details: object,
): Promise<object[] | undefined>
Recupera información sobre todos los marcos de una pestaña determinada.
Parámetros
-
detalles
objeto
Información sobre la pestaña de la que se recuperarán todos los marcos.
-
tabId
número
Es el ID de la pestaña.
-
Muestra
-
Promise<object[] | undefined>
Chrome 93 y versiones posteriores browser.* desde Chrome 148
getFrame()
browser.webNavigation.getFrame(
details: object,
): Promise<object | undefined>
Recupera información sobre el marco determinado. Un marco 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 marco.
Parámetros
-
detalles
objeto
Es la información sobre el fotograma del que se recuperará información.
-
documentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es el UUID del documento. Si se proporcionan frameId o tabId, se validarán para que coincidan con el documento que se encontró con el ID de documento proporcionado.
-
frameId
number opcional
Es el ID del marco en la pestaña determinada.
-
processId
number opcional
Obsoleto desde Chrome 49Ahora, los marcos se identifican de forma inequívoca por su ID de pestaña y su ID de marco. El ID de proceso ya no es necesario y, por lo tanto, se ignora.
Es el ID del proceso que ejecuta el renderizador de esta pestaña.
-
tabId
number opcional
Es el ID de la pestaña en la que se encuentra el marco.
-
Muestra
-
Promise<object | undefined>
Chrome 93 y versiones posteriores browser.* desde Chrome 148
Eventos
onBeforeNavigate
browser.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Se activa cuando está por ocurrir una navegación.
Parámetros
-
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
objeto
-
Chrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos para una pestaña y un proceso determinados.
-
Chrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
número
Es el ID del marco superior o
-1si este es el marco principal. -
número
Obsoleto desde Chrome 50Ya no se establece el processId para este evento, ya que el proceso que renderizará el documento resultante no se conoce hasta onCommit.
El valor de -1.
-
número
Es el ID de la pestaña en la que se producirá la navegación.
-
número
Es el momento en 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.
-
onCommitted
browser.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 submarcos) aún se estén descargando, pero al menos parte del documento se recibió del servidor y el navegador decidió cambiar al documento nuevo.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Es el ID del proceso que ejecuta el renderizador de este marco.
-
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 que se confirmó la navegación, en milisegundos desde la época.
-
transitionQualifiers
Es una lista de calificadores de transición.
-
transitionType
Es la causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Son las condiciones que debe cumplir la URL a la que se navega.
-
onCompleted
browser.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
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Es el ID del proceso que ejecuta el renderizador de este marco.
-
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 que el documento terminó de cargarse, en milisegundos desde la época.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Son las condiciones que debe cumplir la URL a la que se navega.
-
onCreatedNavigationTarget
browser.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
callbackse ve de la siguiente manera:(details: object) => void
-
objeto
-
número
Es el ID del marco con sourceTabId en el que se activa la navegación. El valor 0 indica el marco principal.
-
número
Es el ID del proceso que ejecuta el renderizador para el marco de origen.
-
número
Es el ID de la pestaña en la que se activa la navegación.
-
número
Es el ID de la pestaña en la que se abre la URL.
-
número
Es la hora en 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.
-
onDOMContentLoaded
browser.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Se activa cuando el DOM de la página se construye por completo, pero es posible que los recursos a los que se hace referencia no terminen de cargarse.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Es el ID del proceso que ejecuta el renderizador de este marco.
-
tabId
número
Es el ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Es el momento en 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.
-
onErrorOccurred
browser.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Se activa cuando se produce un error y se anula la navegación. Esto puede suceder si se produjo un error de red o si el usuario anuló la navegación.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Obsoleto desde Chrome 50El processId ya no se establece para este evento.
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 hora en que se produjo 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.
-
onHistoryStateUpdated
browser.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Se activa cuando el historial del marco se actualizó a una URL nueva. Todos los eventos futuros de ese marco usarán la URL actualizada.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Es el ID del proceso que ejecuta el renderizador de este marco.
-
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 que se confirmó la navegación, en milisegundos desde la época.
-
transitionQualifiers
Es una lista de calificadores de transición.
-
transitionType
Es la causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Son las condiciones que debe cumplir la URL a la que se navega.
-
onReferenceFragmentUpdated
browser.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Se activa cuando se actualiza el fragmento de referencia de un marco. Todos los eventos futuros de ese marco usarán la URL actualizada.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posteriores browser.* desde Chrome 148Un UUID del documento cargado.
-
documentLifecycleChrome 106 y versiones posteriores browser.* desde Chrome 148
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 submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores browser.* desde Chrome 148
Es el tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posteriores browser.* desde Chrome 148Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posteriores browser.* desde Chrome 148Es el ID del marco superior o
-1si este es el marco principal. -
processId
número
Es el ID del proceso que ejecuta el renderizador de este marco.
-
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 que se confirmó la navegación, en milisegundos desde la época.
-
transitionQualifiers
Es una lista de calificadores de transición.
-
transitionType
Es la causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Son las condiciones que debe cumplir la URL a la que se navega.
-
onTabReplaced
browser.webNavigation.onTabReplaced.addListener(
callback: function,
)
Se activa cuando el contenido de la pestaña se reemplaza por una pestaña diferente (por lo general, renderizada previamente).
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
replacedTabId
número
Es el ID de la pestaña que se reemplazó.
-
tabId
número
Es el ID de la pestaña que reemplazó a la anterior.
-
timeStamp
número
Es la hora en que se produjo el reemplazo, expresada en milisegundos desde la época.
-
-