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 URL en el historial del navegador. Para anular la página del historial con tu propia versión, consulta Anular páginas.

Permisos

history

Para interactuar con el historial de navegación del usuario, usa la API de History.

Para usar la API de History, declara el permiso "history" en el manifiesto de extensión. Por ejemplo:

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

Conceptos y uso

Tipos de transición

La API de History usa tipos 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 haciendo clic en un vínculo de otra página, el el tipo de transición es “link”. Consulta el contenido de referencia para obtener una lista de tipos de transición.

Ejemplos

Para probar esta API, instala el ejemplo de la API de historial desde chrome-extension-samples en un repositorio de confianza.

Tipos

HistoryItem

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

Propiedades

  • id

    string

    Es el identificador único del artículo.

  • lastVisitTime

    número opcional

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

  • título

    string 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 al escribir la dirección.

  • url

    string opcional

    Es la URL hasta la que un usuario navegó.

  • 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 desde su URL de referencia.

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. Esto también se usa para otras acciones de navegación explícitas.

"auto_bookmark"
El usuario llegó a esta página mediante 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 submarco que no solicitó, por ejemplo, a través de la carga de un anuncio en un marco de la página anterior. Estas no siempre generan nuevas entradas de navegación en los menús para ir hacia atrás y hacia adelante.

"manual_subframe"
El usuario llegó a esta página seleccionando un elemento 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, por ejemplo, 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 el usuario podría verla como "Buscar en Google ...". Son diferentes de las navegaciones escritas porque el usuario no escribió ni vio la URL de destino. También están relacionadas 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 completando valores en un formulario y enviándolo. No todos los formularios enviados utilizan este tipo de transición.

"reload"
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 pestaña cerrada Reabrir 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 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

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

VisitItem

Un objeto que encapsula una visita a una URL.

Propiedades

  • id

    string

    Es el identificador único del history.HistoryItem correspondiente.

  • isLocal

    boolean

    Chrome 115 y versiones posteriores

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

  • referringVisitId

    string

    Es el ID de visita del referente.

  • transition

    TransitionType

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

  • visitId

    string

    Es el identificador único de esta visita.

  • visitTime

    número opcional

    Indica cuándo ocurrió esta visita, representada 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 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: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

deleteAll()

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

Borra todos los elementos del historial.

Parámetros

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

deleteRange()

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

Elimina todos los elementos dentro del período especificado del historial. Las páginas no se eliminarán del historial, a menos que todas las visitas estén dentro del rango.

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

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

deleteUrl()

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

Quita del historial todas las apariciones de la URL dada.

Parámetros

  • detalles

    UrlDetails

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución 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

Muestra

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

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

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

Parámetros

  • consulta

    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, el valor predeterminado será de 24 horas.

    • texto

      string

      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

Muestra

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onVisited

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

Se activa cuando se visita una URL y se proporcionan los datos de HistoryItem de 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) => 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, la URL se borra definitivamente del historial.

Parámetros

  • callback

    función

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

    (removed: object) => void

    • quitado

      objeto

      • allHistory

        boolean

        Es verdadero si se quitó todo el historial. Si esta preferencia se establece como "true", las URLs estarán vacías.

      • url

        string[] opcional