chrome.history

Descripción

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

Permisos

history

Manifest

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

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

Tipos de transición

La API de History utiliza un tipo de transición para describir cómo el navegador navegó a una URL en particular en una visita en particular. Por ejemplo, si un usuario visita una página cuando hace 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
"escrito"El usuario obtuvo 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 generado, que se usa para los casos en los que el usuario seleccionó una opción que no se ve en absoluto como 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 submarcos. Es 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, esas URLs de anuncios tendrán este tipo de transición. Es posible que el usuario ni siquiera se dé cuenta de que el contenido de estas páginas está en un marco independiente y, por lo tanto, tal vez no le importe la URL (consulta también manual_subframe).
"submarco_manual"Para las navegaciones de submarcos que el usuario solicita explícitamente y genera entradas de navegación nuevas en la lista de atrás/adelante. Es probable que un fotograma solicitado explícitamente sea más importante que uno cargado automáticamente porque es probable que al usuario le interese que el fotograma solicitado se haya cargado.
"generado"El usuario llegó a esta página escribiendo en la barra de direcciones y seleccionando una entrada que no parecía una URL. Por ejemplo, una coincidencia podría tener la URL de una página de resultados de la Búsqueda de Google, pero se le podría mostrar al usuario como "Buscar en Google ...". No son exactamente lo mismo que las navegaciones escritas porque 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 de 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 da lugar a este tipo de transición.
"volver a cargar"El usuario volvió a cargar la página haciendo clic en el botón de volver a cargar o presionando Intro en la barra de direcciones. El restablecimiento de sesión y la de reabrir pestaña cerrada también usan este tipo de transición.
"palabra clave"La URL se generó a partir de una palabra clave reemplazable que no era 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 chrome-extension-samples.

Tipos

HistoryItem

Un objeto que encapsula un resultado de una consulta de historial.

Propiedades

  • id

    cadena

    Es el identificador único del artículo.

  • lastVisitTime

    número opcional

    Indica cuándo se cargó esta página por última vez, se representa en milisegundos desde el ciclo de entrenamiento.

  • título

    cadena opcional

    Indica 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

    La URL a la que navegó un usuario.

  • visitCount

    número opcional

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

TransitionType

Chrome 44 y versiones posteriores

Es el tipo de transición de esta visita a partir de su referente.

Enum

"link"
El usuario llegó a esta página tras hacer 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 mediante una navegación de submarcos que no solicitó, por ejemplo, mediante la carga de un anuncio en un marco en la página anterior. Estas no siempre generan entradas de navegación nuevas en los menús Atrás y Avanzar.

"manual_subframe"
El usuario llegó a esta página seleccionando algo en un submarco.

"generado"
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 podría tener la URL de una página de resultados de la Búsqueda de Google, pero se le podría mostrar 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 la navegación 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 completando los valores de un formulario y lo envió. No todos los envíos de formularios utilizan este tipo de transición.

"volver a cargar"
El usuario volvió a cargar la página, ya sea haciendo clic en el botón de volver a cargar o presionando Intro en la barra de direcciones. El restablecimiento de sesión y la de reabrir pestaña cerrada también usan este tipo de transición.

"palabra clave"
La URL de esta página se generó a partir de una palabra clave reemplazable distinta del proveedor de búsqueda predeterminado.

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

UrlDetails

Chrome 88 y versiones posteriores

Propiedades

  • url

    cadena

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

VisitItem

Es un objeto que encapsula una visita a una URL.

Propiedades

  • id

    cadena

    Es el identificador único del history.HistoryItem correspondiente.

  • isLocal

    boolean

    Chrome 115 y versiones posteriores

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

  • referringVisitId

    cadena

    Es el ID de visita del referente.

  • transition

    TransitionType

    Es el tipo de transición de esta visita a partir de su referente.

  • visitId

    cadena

    Es el identificador único de esta visita.

  • visitTime

    número opcional

    Indica cuándo ocurrió esta visita, se representa en milisegundos desde el ciclo de entrenamiento.

Métodos

addUrl()

Promesa 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Agrega una URL al historial en la hora actual con el tipo de transición "link".

Parámetros

  • detalles

    UrlDetails

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteAll()

Promesa 
chrome.history.deleteAll(
  callback?: function,
)

Elimina todos los elementos del historial.

Parámetros

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteRange()

Promesa 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

Parámetros

  • rango

    objeto

    • endTime

      número

      Elementos agregados al historial antes de esta fecha, representados en milisegundos desde el ciclo de entrenamiento.

    • startTime

      número

      Elementos agregados 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: 

    ()=>void

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

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

deleteUrl()

Promesa 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Quita del historial todas las apariciones de la URL especificada.

Parámetros

  • detalles

    UrlDetails

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

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

getVisits()

Promesa 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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[])=>void

Devuelve

  • Promise<VisitItem[]>

    Chrome 96 y versiones posteriores

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

Promesa 
chrome.history.search(
  query: object,
  callback?: function,
)

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

Parámetros

  • búsqueda

    objeto

    • endTime

      número opcional

      Limita los resultados a aquellos visitados antes de esta fecha, representados en milisegundos desde el ciclo de entrenamiento.

    • maxResults

      número opcional

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

    • startTime

      número opcional

      Limita los resultados a aquellos visitados después de esta fecha, representados en milisegundos desde el ciclo de entrenamiento. Si no se especifica la propiedad, la configuración predeterminada será de 24 horas.

    • text

      cadena

      Una consulta de texto libre al servicio de historial. Deja este campo vacío para recuperar todas las páginas.

  • callback

    Función opcional

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

    (results: HistoryItem[])=>void

Devuelve

  • Promise<HistoryItem[]>

    Chrome 96 y versiones posteriores

    Las promesas solo son compatibles con 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, lo que proporciona los datos de HistoryItem para esa URL. Este evento se activa antes de que se cargue la página.

Parámetros

  • callback

    la función

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

    (result: HistoryItem)=>void

onVisitRemoved

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

Se activa cuando se quitan una o más URLs del historial. Una vez que se hayan quitado todas las visitas, la URL se borrará definitivamente del historial.

Parámetros

  • callback

    la función

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

    (removed: object)=>void

    • eliminada

      objeto

      • allHistory

        boolean

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

      • urls

        string[] opcional