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
Manifiesto
Debes declarar el "historial" permiso en el manifiesto de extensión para usar la API de History. 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 haciendo clic en un vínculo de otra página, el el tipo de transición es “link”.
En la siguiente tabla, se describe cada tipo de transición.
Tipo de transición | Descripción |
---|---|
"vínculo" | El usuario llegó a esta página haciendo clic en un vínculo de otra página. |
"typed" | El usuario obtuvo esta página al escribir la URL en la barra de direcciones. También se usa para otras acciones de navegación explícitas. Consulta también la sección Generado, que se usa para los casos en los que el usuario seleccionó una opción que no se parece en absoluto a una URL. |
"marcador_automático" | 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 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, por lo que tal vez no le interese la URL (consulta también manual_subframe). |
"manual_subframe" | Para las navegaciones de submarcos que el usuario solicita de manera explícita y que generan nuevas entradas de navegación en la lista de atrás/adelante. Un fotograma solicitado explícitamente probablemente sea más importante que un fotograma cargado automáticamente porque al usuario probablemente le importa el hecho de que se haya cargado el fotograma solicitado. |
“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 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 ...". No son exactamente lo mismo que las navegaciones escribe porque el usuario no escribió o no 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ó. Tenga en cuenta que en algunos casos, como cuando un formulario utiliza una secuencia de comandos para enviar contenido, el envío de un formulario no genera 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 la sesión y la pestaña cerrada Reabrir 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 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
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
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 posterioresVerdadero 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
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()
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
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
deleteAll()
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
deleteRange()
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Quita del historial todas las apariciones de la URL dada.
Parámetros
-
detalles
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Recupera información sobre las visitas a una URL.
Parámetros
-
detalles
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(results: VisitItem[]) => void
-
resultados
-
Muestra
-
Promise<VisitItem[]>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
search()
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
-
resultados
-
Muestra
-
Promise<HistoryItem[]>
Chrome 96 y versiones posterioresLas 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 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
-
resultado
-
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
-
-