chrome.history

refresh date: 2026-09-25 robots: noindex

Descripción

Usa la API de chrome.history para interactuar con el registro de páginas visitadas del navegador. Puedes agregar, quitar y consultar URLs en el historial del navegador. Para reemplazar la página del historial con tu propia versión, consulta Override Pages.

Permisos

history

Manifiesto

Debes declarar el permiso "history" en el manifiesto de la extensión para usar la API de History. Por ejemplo:

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

Tipos de transición

La API de History usa un tipo de transición para describir cómo el navegador navegó a una URL específica en una visita en particular. Por ejemplo, si un usuario visita una página haciendo clic en un vínculo de otra página, el tipo de transición es "vínculo".

En la siguiente tabla, se describe cada tipo de transición.

Tipo de transiciónDescripción
"typed"El usuario llegó a esta página escribiendo la URL en la barra de direcciones. También se usa para otras acciones de navegación explícitas. Consulta también generated, que se usa en los casos en los que el usuario seleccionó una opción que no se parecía en absoluto a una URL.
"auto_bookmark"El usuario llegó a esta página a través de una sugerencia en la IU, por ejemplo, a través de un elemento de menú.
"auto_subframe"Navegación por subframes Se trata de cualquier contenido que se carga automáticamente en un marco que no es de nivel superior. Por ejemplo, si una página consta de varios marcos que contienen anuncios, las URLs de esos anuncios tienen este tipo de transición. Es posible que el usuario ni siquiera se dé cuenta de que el contenido de estas páginas es un marco independiente y, por lo tanto, no le interese la URL (consulta también manual_subframe).
"manual_subframe"Para las navegaciones de subframes que el usuario solicita de forma explícita y que generan nuevas entradas de navegación en la lista de atrás/adelante. Un fotograma solicitado de forma explícita probablemente sea más importante que uno cargado automáticamente, ya que es probable que al usuario le preocupe el hecho de que se haya cargado el fotograma solicitado.
"generated"El usuario llegó a esta página ingresando texto en la barra de direcciones y seleccionando una entrada que no parecía una URL. Por ejemplo, una coincidencia puede tener la URL de una página de resultados de la Búsqueda de Google, pero puede aparecerle al usuario como "Buscar en Google…". No son exactamente iguales a las navegaciones escritas, ya que el usuario no escribió ni vio la URL de destino. Consulta también palabra clave.
"auto_toplevel"La página se especificó en la línea de comandos o es la página de inicio.
"form_submit"El usuario completó los valores en un formulario y lo envió. Ten en cuenta que, en algunas situaciones, como cuando un formulario usa una secuencia de comandos para enviar contenido, el envío de un formulario no genera este tipo de transición.
"reload"El usuario volvió a cargar la página haciendo clic en el botón de recarga o presionando Intro en la barra de direcciones. La función para restablecer sesiones y la opción para volver a abrir pestañas cerradas también usan este tipo de transición.
"palabra clave"La URL se generó a partir de una palabra clave reemplazable que no es el proveedor de búsqueda predeterminado. Consulta también keyword_generated.
"keyword_generated"Corresponde a una visita generada para una palabra clave. Consulta también palabra clave.

Ejemplos

Para probar esta API, instala el ejemplo de la API de History desde el repositorio de chrome-extension-samples.

Tipos

HistoryItem

Objeto que encapsula un resultado de una consulta de historial.

Propiedades

  • id

    string

    Es el identificador único del elemento.

  • lastVisitTime

    número opcional

    Fecha y hora en que se cargó esta página por última vez, representada en milisegundos desde la época.

  • título

    cadena opcional

    Es el título de la página cuando se cargó por última vez.

  • typedCount

    número opcional

    Indica la cantidad de veces que el usuario navegó a esta página escribiendo la dirección.

  • url

    cadena opcional

    Es la URL a la que navegó un usuario.

  • visitCount

    número opcional

    Es la cantidad de veces que el usuario navegó a esta página.

TransitionType

Chrome 44 y versiones posteriores

Es el tipo de transición para esta visita desde su sitio de referencia.

Enum

"link"
El usuario llegó a esta página haciendo clic en un vínculo de otra página.

"typed"
El usuario llegó a esta página escribiendo la URL en la barra de direcciones. También se usa para otras acciones de navegación explícitas.

"auto_bookmark"
El usuario llegó a esta página a través de una sugerencia en la IU, por ejemplo, a través de un elemento de menú.

"auto_subframe"
El usuario llegó a esta página a través de una navegación de subframe que no solicitó, por ejemplo, a través de un anuncio que se cargó en un frame de la página anterior. No siempre generan nuevas entradas de navegación en los menús atrás y adelante.

"manual_subframe"
El usuario llegó a esta página después de seleccionar algo en un subframe.

"generated"
El usuario llegó a esta página escribiendo en la barra de direcciones y seleccionando una entrada que no parecía una URL, como una sugerencia de la Búsqueda de Google. Por ejemplo, una coincidencia puede tener la URL de una página de resultados de la Búsqueda de Google, pero puede aparecerle al usuario como "Buscar en Google…". Estas son diferentes de las navegaciones escritas porque el usuario no escribió ni vio la URL de destino. También se relacionan con las navegaciones por palabras clave.

"auto_toplevel"
La página se especificó en la línea de comandos o es la página de inicio.

"form_submit"
El usuario llegó a esta página después de completar los valores en un formulario y enviarlo. No todos los envíos de formularios usan este tipo de transición.

"reload"
El usuario volvió a cargar la página haciendo clic en el botón de recarga o presionando Intro en la barra de direcciones. La función para restablecer sesiones y la opción para volver a abrir pestañas cerradas también usan este tipo de transición.

"keyword"
La URL de esta página se generó a partir de una palabra clave reemplazable que no es el proveedor de búsqueda predeterminado.

"keyword_generated"
Corresponde a una visita generada para una palabra clave.

UrlDetails

Chrome 88 y versiones posteriores

Propiedades

  • url

    string

    Es la URL de la operación. Debe tener el formato que se muestra en la respuesta de una llamada a history.search().

VisitItem

Es un objeto que encapsula una visita a una URL.

Propiedades

  • id

    string

    Es el identificador único del objeto history.HistoryItem correspondiente.

  • isLocal

    booleano

    Chrome 115 y versiones posteriores

    Es verdadero si la visita se originó en este dispositivo. Es falso si se sincronizó desde otro dispositivo.

  • referringVisitId

    string

    Es el ID de la visita del sitio de referencia.

  • transición

    TransitionType

    Es el tipo de transición para esta visita desde su sitio de referencia.

  • visitId

    string

    Es el identificador único de esta visita.

  • visitTime

    número opcional

    Fecha y hora en que se produjo la visita, representada en milisegundos desde la época.

Métodos

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

Agrega una URL al historial en el momento actual con un tipo de transición de "vínculo".

Parámetros

  • detalles

    UrlDetails

  • callback

    función opcional

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

    () =& gt;void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

Borra todos los elementos del historial.

Parámetros

  • callback

    función opcional

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

    () =& gt;void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

Quita del historial todos los elementos dentro del período especificado. Las páginas no se quitarán del historial, a menos que todas las visitas se encuentren dentro del período.

Parámetros

  • rango

    objeto

    • endTime

      número

      Son los elementos que se agregaron al historial antes de esta fecha, representados en milisegundos desde el ciclo de entrenamiento.

    • startTime

      número

      Son los elementos que se agregaron al historial después de esta fecha, representados en milisegundos desde el ciclo de entrenamiento.

  • callback

    función opcional

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

    () =& gt;void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

Quita todas las ocurrencias de la URL determinada del historial.

Parámetros

  • detalles

    UrlDetails

  • callback

    función opcional

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

    () =& gt;void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

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

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

Recupera información sobre las visitas a una URL.

Parámetros

  • detalles

    UrlDetails

  • callback

    función opcional

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

    (results: VisitItem[]) =& gt;void

Muestra

  • Promise<VisitItem[]>

    Chrome 96 y versiones posteriores

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

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

Busca en el historial la hora de la última visita de cada página que coincide con la búsqueda.

Parámetros

  • consulta

    objeto

    • endTime

      número opcional

      Limita los resultados a los que se visitaron antes de esta fecha, representada en milisegundos desde la época.

    • maxResults

      número opcional

      Es la cantidad máxima de resultados que se recuperarán. La configuración predeterminada es 100.

    • startTime

      número opcional

      Limita los resultados a los que se visitaron después de esta fecha, representada en milisegundos desde la época. Si no se especifica la propiedad, el valor predeterminado será 24 horas.

    • texto

      string

      Es una consulta de texto libre al servicio de historial. Déjalo vacío para recuperar todas las páginas.

  • callback

    función opcional

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

    (results: HistoryItem[]) =& gt;void

Muestra

  • Promise<HistoryItem[]>

    Chrome 96 y versiones posteriores

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

Eventos

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

Se activa cuando se visita una URL y proporciona los datos de HistoryItem para esa URL. Este evento se activa antes de que se cargue la página.

Parámetros

  • callback

    función

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

    (result: HistoryItem) =& gt;void

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

Se activa cuando se quitan una o más URLs del historial. Cuando se quitan todas las visitas, se borra la URL del historial.

Parámetros

  • callback

    función

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

    (removed: object) =& gt;void

    • quitado

      objeto

      • allHistory

        booleano

        Es verdadero si se quitó todo el historial. Si es verdadero, las URLs estarán vacías.

      • url

        cadena[] opcional