Descripción
Usa la API de chrome.webNavigation
para recibir notificaciones sobre el estado de las solicitudes de navegación en tránsito.
Permisos
webNavigation
Todos los métodos y eventos chrome.webNavigation
requieren que declares el permiso "webNavigation"
en el manifiesto de extensión. Por ejemplo:
{
"name": "My extension",
...
"permissions": [
"webNavigation"
],
...
}
Conceptos y uso
Orden del evento
Para que una navegación se complete correctamente, los eventos se activan en el siguiente orden:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
Cualquier error que ocurra durante el proceso dará como resultado un evento onErrorOccurred
. Para una configuración
navegación, no se activan más eventos después de onErrorOccurred
.
Si un fotograma de navegación contiene submarcos, su onCommitted
se activa antes que el segundo
onBeforeNavigate
; mientras que onCompleted
se activa después de todos los onCompleted
de sus elementos secundarios.
Si se cambia el fragmento de referencia de un fotograma, se activa un evento onReferenceFragmentUpdated
. Esta
puede activarse en cualquier momento después de onDOMContentLoaded
, incluso después de onCompleted
.
Si la API de History se usa para modificar el estado de un fotograma (por ejemplo, con history.pushState()
, se
Se activó el evento onHistoryStateUpdated
. Este evento puede activarse en cualquier momento después del onDOMContentLoaded
.
Si una navegación restableció una página de la Memoria caché anterior, el evento onDOMContentLoaded
no se activará. El evento no se activa porque el contenido ya terminó de cargarse cuando la página
se visitó por primera vez.
Si se activa la navegación con Chrome Instant o Instant Pages, se mostrará
la página se cambiará a 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 la API de webNavigation. Es posible que aún se reciban eventos de webRequest para los marcos que ya inició una nueva navegación, o bien que esta solo continúa cuando los recursos de red ya están completamente cargado.
En general, los eventos 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 se generalmente opacos para el usuario.
IDs de pestaña
No todas las pestañas de navegación corresponden a pestañas reales en la IU de Chrome, por ejemplo, una pestaña que
prerrenderizada. No se puede acceder a esas pestañas con la API de Tabs y no puedes solicitar información
sobre ellos llamando a webNavigation.getFrame()
o webNavigation.getAllFrames()
. Una vez que esta pestaña
se intercambia, se activa un evento onTabReplaced
y se puede acceder a ellos a través de estas APIs.
Marcas de tiempo
Es importante tener en cuenta que algunas peculiaridades técnicas en el manejo del SO diferenciado en Chrome
pueden hacer que el reloj se distorsione entre el navegador y los procesos de extensión. Que
significa que la propiedad timeStamp
de la propiedad timeStamp
del evento WebNavigation
solo está garantizada
tengan coherencia interna. Si comparas un evento con otro, obtendrás el ajuste correcto.
entre ellas, pero compararlas con la hora actual dentro de la extensión (con (new Date()).getTime()
,
por ejemplo) pueden dar resultados inesperados.
IDs de marco
Los marcos dentro de una pestaña se pueden identificar por un ID de marco. El ID del marco principal es siempre 0; el El ID de los marcos secundarios es un número positivo. Una vez que se crea un documento en un marco, su ID de marco se mantiene constante durante el ciclo de vida del documento. A partir de Chrome 49, este ID también es constante para la vida útil del fotograma (en varias navegaciones).
Debido a la naturaleza de varios procesos de Chrome, es posible que una pestaña use diferentes procesos para renderizar la fuente.
y el destino de una página web. Por lo tanto, si la navegación ocurre
en un proceso nuevo, podrías
recibir eventos tanto de la página nueva como de la anterior hasta que se confirme la navegación nueva (es decir, el
Se envía el evento onCommitted
para el nuevo marco principal). En otras palabras, es posible tener más
más de una secuencia pendiente de eventos de webNavigation con el mismo frameId
Las secuencias pueden ser
que se distingue con la tecla processId
.
Además, ten en cuenta que, durante una carga provisional, el proceso puede cambiarse varias veces. Esto sucede
cuando la carga se redirecciona a otro sitio. En este caso, recibirás solicitudes reiteradas
onBeforeNavigate
y onErrorOccurred
hasta que recibas el último evento de onCommitted
.
Otro concepto problemático con las extensiones es el ciclo de vida de las marco. Un marco aloja un documento (que está asociado con una URL confirmada). El documento puede cambiar (por ejemplo, navegando), pero el frameId no lo hará, por lo que es difícil asociar que algo ocurrió en un documento específico con solo frameIds. Presentamos un concepto de documentId que es un identificador único por documento. Si se navega por un marco y se abre un nuevo documento, cambiará el identificador. Este campo es útil para determinar Cuando las páginas cambian el estado de su ciclo de vida (entre renderización previa, activa o almacenada en caché) porque sigue siendo igual.
Tipos de transición y calificadores
El evento webNavigation
onCommitted
tiene una transitionType
y una transitionQualifiers
propiedad. El tipo de transición es el mismo que se usa en la API de History, que describe cómo
navegador navegó a esta URL en particular. Además, se pueden usar varios calificadores de transición
que se muestran y que definen aún más la navegación.
Existen los siguientes calificadores de transición:
Calificador de transición | Descripción |
---|---|
"redireccionamiento_cliente" | Uno o más redireccionamientos causados por JavaScript o las metaetiquetas de actualización de la página se produjeron durante la navegación. |
"redireccionamiento_servidor" | Uno o más redireccionamientos causados por encabezados HTTP enviados desde el servidor se produjeron durante la navegación. |
"forward_back" | El usuario utilizó el botón Avanzar 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 chrome-extension-samples en un repositorio de confianza.
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 definidos en la API de History. Estos son los mismos tipos de transición que se definen en la API de History, excepto con "start_page"
en lugar de "auto_toplevel"
(para la retrocompatibilidad).
Enum
“vínculo”
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
“generado”
"start_page"
"form_submit"
“reload”
“palabra clave”
"keyword_generated"
Métodos
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
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
El ID de la pestaña.
-
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(details?: object[]) => void
-
detalles
object[] opcional
Una lista de fotogramas en la pestaña determinada, cuyo valor es nulo si el ID de pestaña especificado no es válido.
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
errorOccurred
boolean
Es verdadero si un error interrumpió la última navegación en este fotograma, es decir, si se activó el evento onErrorOccurred.
-
frameId
número
El ID del marco. 0 indica que este es el marco principal; un valor positivo indica el ID de un submarco.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
El ID del marco superior, o
-1
si este es el marco principal -
processId
número
Es el ID del proceso que ejecuta el renderizador para este fotograma.
-
url
string
La URL actualmente asociada con este marco.
-
-
Muestra
-
Promise<object[] | indefinido>
Chrome 93 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.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
Recupera información sobre un fotograma 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
Información sobre el fotograma sobre el que se recuperará información.
-
documentId
string 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
El ID del marco en la pestaña determinada.
-
processId
número opcional
Obsoleto desde Chrome 49Los fotogramas ahora se identifican de forma única por su ID de pestaña y 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
El ID de la pestaña en la que se encuentra el marco.
-
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(details?: object) => void
-
detalles
objeto opcional
Información sobre el fotograma solicitado, nulo si el ID de marco especificado o el ID de pestaña no son válidos.
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
errorOccurred
boolean
Es verdadero si un error interrumpió la última navegación en este fotograma, es decir, si se activó el evento onErrorOccurred.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
El ID del marco superior, o
-1
si este es el marco principal -
url
string
La URL actualmente asociada con este marco, si el marco identificado por el frameId existía en un punto de la pestaña determinada. El hecho de que una URL esté asociada con un frameId determinado no implica que el marco correspondiente aún exista.
-
-
Muestra
-
Promise<object | indefinido>
Chrome 93 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
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Se activa cuando una navegación está a punto de ocurrir.
Parámetros
-
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
objeto
-
Chrome 106 y versiones posteriores
El ciclo de vida del documento.
-
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de trama son únicos para una pestaña y un proceso determinados.
-
Chrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
número
El ID del marco superior, 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
El ID de la pestaña en la que se realizará la navegación.
-
número
Indica el momento en que el navegador estaba a punto de iniciar la navegación, en milisegundos desde el ciclo de entrenamiento.
-
string
-
-
-
objeto opcional
-
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter 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 submarcos) aún se esté 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
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, 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
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Es el tiempo en que se confirmó la navegación, en milisegundos desde el ciclo de entrenamiento.
-
transitionQualifiers
Una lista de calificadores de transición.
-
transitionType
Causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter 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) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, 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
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Es el tiempo en que el documento terminó de cargarse, en milisegundos, desde el ciclo de entrenamiento.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter 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) => void
-
objeto
-
número
El ID del marco con sourceTabId en el que se activa la navegación. 0 indica el marco principal.
-
número
Es el ID del proceso que ejecuta el renderizador para el fotograma de origen.
-
número
El ID de la pestaña en la que se activa la navegación.
-
número
El ID de la pestaña en la que se abre la URL
-
número
Indica el tiempo en que el navegador estaba a punto de crear una vista nueva, en milisegundos desde el ciclo de entrenamiento.
-
string
La URL que se abrirá en la nueva ventana
-
-
-
objeto opcional
-
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter para este evento.
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Se activa cuando el DOM de la página está completamente construido, 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) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, 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
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Indica la hora en que el DOM de la página se construyó por completo, en milisegundos, desde el ciclo de entrenamiento.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter para este evento.
-
onErrorOccurred
chrome.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 produce un error de red o si el usuario anuló la navegación.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
error
string
La descripción del error.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, o
-1
si este es el marco principal -
processId
número
Obsoleto desde Chrome 50El processId ya no está establecido para este evento.
Es el valor de -1.
-
tabId
número
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
El tiempo en que se produjo el error, en milisegundos desde el ciclo de entrenamiento.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter para este evento.
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Se activa cuando el historial del fotograma se actualiza a una URL nueva. Todos los eventos futuros para ese marco usarán la URL actualizada.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, 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
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Es el tiempo en que se confirmó la navegación, en milisegundos desde el ciclo de entrenamiento.
-
transitionQualifiers
Una lista de calificadores de transición.
-
transitionType
Causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter 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 para ese marco usarán la URL actualizada.
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
documentId
string
Chrome 106 y versiones posterioresSe carga un UUID del documento.
-
documentLifecycleChrome 106 y versiones posteriores
El ciclo de vida del documento.
-
frameId
número
0 indica que la navegación se realiza en la ventana de contenido de la pestaña; un valor positivo indica la navegación en un submarco. Los IDs de marco son únicos dentro de una pestaña.
-
frameTypeChrome 106 y versiones posteriores
El tipo de marco en el que se produjo la navegación.
-
parentDocumentId
string opcional
Chrome 106 y versiones posterioresUn UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.
-
parentFrameId
número
Chrome 74 y versiones posterioresEl ID del marco superior, 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
El ID de la pestaña en la que se produce la navegación.
-
timeStamp
número
Es el tiempo en que se confirmó la navegación, en milisegundos desde el ciclo de entrenamiento.
-
transitionQualifiers
Una lista de calificadores de transición.
-
transitionType
Causa de la navegación.
-
url
string
-
-
-
filtros
objeto opcional
-
url
Condiciones que debe cumplir la URL a la que se navega. Los esquemas y 'ports' Se ignoran los campos de UrlFilter 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 (por lo general, previamente renderizada previamente).
Parámetros
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
replacedTabId
número
El ID de la pestaña que se reemplazó.
-
tabId
número
El ID de la pestaña que reemplazó a la pestaña anterior
-
timeStamp
número
La hora en la que se produjo el reemplazo, en milisegundos desde el ciclo de entrenamiento.
-
-