chrome.webNavigation

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

Manifiesto

Todos los métodos y eventos de chrome.webNavigation requieren que declares "webNavigation" permiso en el manifiesto de extensión. Por ejemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

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 la navegación se activaba a través de Chrome Instant o Instant Pages, se cargaría por completo 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, p.ej., una pestaña que se está creando prerrenderizada. No se puede acceder a estas pestañas a través de la API de Tabs y no puedes solicitar información sobre ellos a través de webNavigation.getFrame o webNavigation.getAllFrames. Cuando se intercambia esa pestaña se activa un evento onTabReplaced y se puede acceder a ellos mediante 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 los eventos de WebNavigation Solo se garantiza que la propiedad timeStamp es interna coherentes. Si comparas un evento con otro, obtendrás el desplazamiento correcto entre ellos, pero comparándolos con la hora actual en la extensión (por ejemplo, mediante (new Date()).getTime()) podría 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 onCommitted de la API de webNavigation tiene un transitionType y un 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ónDescripció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

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 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()

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

        Se carga un UUID del documento.

      • documentLifecycle

        DocumentLifecycle

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

      • frameType

        FrameType

        Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getFrame()

Promesa 
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 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

      El ID del marco en la pestaña determinada.

    • processId

      número opcional

      Obsoleto desde Chrome 49

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

        Se carga un UUID del documento.

      • documentLifecycle

        DocumentLifecycle

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

      • frameType

        FrameType

        Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Un 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&lt;object | indefinido>

    Chrome 93 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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

  • callback

    función

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

    (details: object) => void

    • detalles

      objeto

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Un 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

        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

        El ID de la pestaña en la que se realizará la navegación.

      • timeStamp

        número

        Indica el momento en que el navegador estaba a punto de iniciar la navegación, en milisegundos desde el ciclo de entrenamiento.

      • url

        string

  • filtros

    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 posteriores

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        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.

      • 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

        TransitionQualifier[]

        Una lista de calificadores de transición.

      • transitionType

        TransitionType

        Causa de la navegación.

      • url

        string

  • filtros

    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.

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 posteriores

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        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.

      • 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

    • Condiciones que deben 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

  • callback

    función

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

    (details: object) => void

    • detalles

      objeto

      • sourceFrameId

        número

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

      • sourceProcessId

        número

        Es el ID del proceso que ejecuta el renderizador para el fotograma de origen.

      • sourceTabId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        Indica el tiempo en que el navegador estaba a punto de crear una vista nueva, en milisegundos desde el ciclo de entrenamiento.

      • url

        string

        La URL que se abrirá en la nueva ventana

  • filtros

    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 posteriores

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        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.

      • 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

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

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        El ID del marco superior, o -1 si este es el marco principal

      • processId

        número

        Obsoleto desde Chrome 50

        El 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

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

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        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.

      • 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

        TransitionQualifier[]

        Una lista de calificadores de transición.

      • transitionType

        TransitionType

        Causa de la navegación.

      • url

        string

  • filtros

    objeto opcional

    • Condiciones que deben 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 posteriores

        Se carga un UUID del documento.

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

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

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

        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.

      • 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

        TransitionQualifier[]

        Una lista de calificadores de transición.

      • transitionType

        TransitionType

        Causa de la navegación.

      • url

        string

  • filtros

    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.

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.