chrome.webNavigation

refresh date: 2026-09-25 robots: noindex

Descripción

Usa la API de chrome.webNavigation para recibir notificaciones sobre el estado de las solicitudes de navegación en curso.

Permisos

webNavigation

Manifiesto

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"
  ],
  ...
}

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 History 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 desde 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 a través de 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, p.ej., una pestaña que se está renderizando previamente. No se puede acceder a esas pestañas a través de la API de pestañas ni puedes solicitar información sobre ellas a través de 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 los eventos de 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 (por ejemplo, a través de (new Date()).getTime()) 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 onCommitted de la API de webNavigation 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ónDescripció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

Chrome 44 y versiones posteriores

Enum

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 y versiones posteriores

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

Promise 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
): 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.

  • callback

    función opcional

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

    (details?: object[]) => void

    • detalles

      object[] opcional

      Es una lista de marcos en la pestaña determinada, nula si el ID de pestaña especificado no es válido.

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 y versiones posteriores

        El ciclo de vida en el que se encuentra el documento.

      • errorOccurred

        booleano

        Es verdadero si la última navegación en este marco se interrumpió por un error, es decir, se activó el evento onErrorOccurred.

      • frameId

        número

        Es el ID del marco. El valor 0 indica que este es el marco principal, mientras que un valor positivo indica el ID de un submarco.

      • frameType

        FrameType

        Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.

      • parentFrameId

        número

        Es 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 de este marco.

      • url

        string

        Es la URL asociada actualmente con este marco.

Muestra

  • Promise<object[] | undefined>

    Chrome 93 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getFrame()

Promise 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
): 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

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

      Ahora, 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.

  • callback

    función opcional

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

    (details?: object) => void

    • detalles

      objeto opcional

      Información sobre el marco solicitado, nulo si el ID de marco o el ID de pestaña especificados no son válidos.

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 y versiones posteriores

        El ciclo de vida en el que se encuentra el documento.

      • errorOccurred

        booleano

        Es verdadero si la última navegación en este marco se interrumpió por un error, es decir, se activó el evento onErrorOccurred.

      • frameType

        FrameType

        Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.

      • parentFrameId

        número

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

      • url

        string

        Es la URL asociada actualmente con este marco, si el marco identificado por frameId existió en algún momento en la pestaña determinada. El hecho de que una URL esté asociada a un frameId determinado no implica que el marco correspondiente aún exista.

Muestra

  • Promise<object | undefined>

    Chrome 93 y versiones posteriores

    Las promesas solo se admiten en 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 está por ocurrir una navegación.

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

        string opcional

        Chrome 106 y versiones posteriores

        Es un UUID del documento superior al que pertenece este marco. No se establece si no hay un elemento superior.

      • parentFrameId

        número

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

      • processId

        número

        Obsoleto desde Chrome 50

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

      • tabId

        número

        Es el ID de la pestaña en la que se producirá la navegación.

      • timeStamp

        número

        Es el momento en 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.

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é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 callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

        TransitionQualifier[]

        Es una lista de calificadores de transición.

      • transitionType

        TransitionType

        Es la causa de la navegación.

      • url

        string

  • filtros

    objeto opcional

    • Son las condiciones que debe cumplir la URL a la que se navega.

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

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

    • Son las condiciones que debe cumplir la URL a la que se navega.

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

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

      • sourceProcessId

        número

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

      • sourceTabId

        número

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

      • tabId

        número

        Es el ID de la pestaña en la que se abre la URL.

      • timeStamp

        número

        Es la hora en 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.

onDOMContentLoaded

chrome.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 callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

    • Son las condiciones que debe cumplir la URL a la que se navega.

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

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

        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

    • Son las condiciones que debe cumplir la URL a la que se navega.

onHistoryStateUpdated

chrome.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 callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

        TransitionQualifier[]

        Es una lista de calificadores de transición.

      • transitionType

        TransitionType

        Es la causa de la navegación.

      • url

        string

  • filtros

    objeto opcional

    • Son las condiciones que debe cumplir la URL a la que se navega.

onReferenceFragmentUpdated

chrome.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 callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • documentId

        string

        Chrome 106 y versiones posteriores

        Un UUID del documento cargado.

      • Chrome 106 y versiones posteriores

        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.

      • Chrome 106 y versiones posteriores

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

      • parentDocumentId

        string opcional

        Chrome 106 y versiones posteriores

        Es 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

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

        TransitionQualifier[]

        Es una lista de calificadores de transición.

      • transitionType

        TransitionType

        Es la causa de la navegación.

      • url

        string

  • filtros

    objeto opcional

    • Son las condiciones que debe cumplir la URL a la que se navega.

onTabReplaced

chrome.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 callback se 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.