chrome.webNavigation

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ónDescripció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

Chrome 44 y versiones posteriores

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 y versiones posteriores

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 posteriores

      Es 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 49

      Ahora 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

  • callback

    función

    El parámetro callback se ve de la siguiente manera:

    (details: object) =& gt;void

    • detalles

      objeto

      • Chrome 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 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.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.

      • parentFrameId

        número

        ID del marco principal o -1 si este es el marco principal.

      • processId

        número

        Obsoleto desde Chrome 50

        El 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.

      • tabId

        número

        Es el ID de la pestaña en la que está a punto de ocurrir la navegación.

      • timeStamp

        número

        Es la hora en la que el navegador estaba a punto de iniciar la navegación, en milisegundos desde la época.

      • url

        string

  • filtros

    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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID 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

    • 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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID 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

    • 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

  • callback

    función

    El parámetro callback se ve de la siguiente manera:

    (details: object) =& gt;void

    • detalles

      objeto

      • sourceFrameId

        número

        Es el ID del frame con sourceTabId en el que se activa la navegación. El 0 indica el fotograma principal.

      • sourceProcessId

        número

        Es el ID del proceso que ejecuta el renderizador para el fotograma fuente.

      • sourceTabId

        número

        ID de la pestaña en la que se activa la navegación.

      • tabId

        número

        ID de la pestaña en la que se abre la URL

      • timeStamp

        número

        Es la hora en la que el navegador estaba a punto de crear una vista nueva, en milisegundos desde la época.

      • url

        string

        Es la URL que se abrirá en la ventana nueva.

  • filtros

    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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID 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

    • 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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID del marco principal o -1 si este es el marco principal.

      • processId

        número

        Obsoleto desde Chrome 50

        El 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

    • 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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID 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

    • 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 posteriores

        Es el UUID del documento cargado.

      • Chrome 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.

      • Chrome 106 y versiones posteriores

        Es el tipo de marco en el que se produjo la navegación.

      • parentDocumentId

        cadena opcional

        Chrome 106 y versiones posteriores

        Es 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 posteriores

        ID 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

    • 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.