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
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 utiliza tipos de transición para describir cómo el navegador navegó a una URL específica en una visita determinada. 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". Consulta el contenido de referencia para obtener una lista de los tipos de transición.
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
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
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 posterioresEs 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
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()
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
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
deleteAll()
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 posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
deleteRange()
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 posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Quita del historial todas las apariciones de la URL especificada.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución 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
-
Devuelve
-
Promise<VisitItem[]>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
search()
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
-
resultados
-
Devuelve
-
Promise<HistoryItem[]>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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, 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
-
resultado
-
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
-
-