Opis
Interfejs API chrome.history
umożliwia interakcję z rejestrem odwiedzonych stron w przeglądarce. Możesz dodawać i usuwać adresy URL oraz tworzyć dotyczące ich zapytania w historii przeglądarki. Aby zastąpić stronę historii własną wersją, przeczytaj sekcję Zastąp strony.
Uprawnienia
history
Aby móc korzystać z historii przeglądania użytkownika, użyj interfejsu History API.
Aby używać interfejsu API historii, zadeklaruj uprawnienie "history"
w pliku manifestu rozszerzenia. Przykład:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
Pojęcia i zastosowanie
Typy przejść
Interfejs History API używa typów przejść do opisania sposobu przechodzenia przez przeglądarkę do określonego adresu URL podczas danej wizyty. Jeśli np. użytkownik otworzy stronę, klikając link na innej stronie, typem przejścia jest „link”. Listę typów przejść znajdziesz w materiałach referencyjnych.
Przykłady
Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs API historii z repozytorium chrome-extension-samples.
Typy
HistoryItem
Obiekt zawierający 1 wynik zapytania dotyczącego historii.
Właściwości
-
id
string,
Unikalny identyfikator elementu.
-
lastVisitTime
Liczba opcjonalnie
Czas ostatniego wczytania strony (w milisekundach od początku epoki).
-
title
ciąg znaków opcjonalny
Tytuł strony podczas ostatniego wczytywania.
-
typedCount
Liczba opcjonalnie
Liczba przejść tej strony przez użytkownika po wpisaniu adresu.
-
URL
ciąg znaków opcjonalny
Adres URL, do którego przeszedł użytkownik.
-
visitCount
Liczba opcjonalnie
Liczba wizyt tej strony przez użytkownika.
Typ wyliczeniowy
"link"
Użytkownik trafił na tę stronę, klikając link na innej stronie.
"typed"
Użytkownik wszedł na tę stronę po wpisaniu jej adresu URL w pasku adresu. Dotyczy to też innych wyraźnych działań związanych z nawigacją.
"auto_bookmark"
Użytkownik dotarł na tę stronę dzięki sugestiom w interfejsie, np. przez pozycję menu.
"auto_subframe"
Użytkownik dotarł na tę stronę za pomocą nawigacji w ramce podrzędnej, o której nie prosił, np. przez wczytywanie reklamy w ramce na poprzedniej stronie. Nie zawsze powodują one generowanie nowych wpisów nawigacyjnych w menu Wstecz i Dalej.
"manual_subframe"
Użytkownik trafił na tę stronę, wybierając coś w ramce podrzędnej.
"generated"
Użytkownik trafił na tę stronę po wpisaniu adresu w pasku adresu i wybraniu wpisu, który nie wygląda jak adres URL, na przykład sugestii wyszukiwarki Google. Dopasowanie może na przykład obejmować adres URL strony wyników wyszukiwania Google, ale użytkownik może zobaczyć takie treści jak „Wyszukaj w Google ...”. Różni się to od wpisywanych elementów nawigacyjnych, ponieważ użytkownik nie wpisał lub nie zobaczył docelowego adresu URL. Są one również związane z poruszaniem się po słowach kluczowych.
"auto_toplevel"
Strona została określona w wierszu poleceń lub jest stroną startową.
"form_submit"
Użytkownik dotarł na tę stronę, wypełniając wartości w formularzu i przesyłając go. Nie wszystkie przesłane formularze korzystają z tego typu przejścia.
"reload"
Użytkownik załadował ponownie stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Tego typu przejścia również używają przywracania sesji i ponownego otwarcia zamkniętej karty.
"keyword"
Adres URL tej strony został wygenerowany na podstawie słowa kluczowego innego niż domyślny dostawca wyszukiwania.
"keyword_generated"
Odpowiada wizyty wygenerowanej przez słowo kluczowe.
UrlDetails
Właściwości
-
URL
string,
Adres URL operacji. Musi mieć format zwracany w wyniku wywołania funkcji
history.search()
.
VisitItem
Obiekt przechowujący jedne odwiedziny adresu URL.
Właściwości
-
id
string,
Unikalny identyfikator odpowiedniego elementu
history.HistoryItem
. -
isLocal
boolean
Chrome 115 i nowsze wersjePrawda, jeśli wizyta miała miejsce na tym urządzeniu. Wartość Fałsz, jeśli została zsynchronizowana z innego urządzenia.
-
referringVisitId
string,
Identyfikator wizyty strony odsyłającej.
-
przenoszenie kont użytkowników
Typ przejścia dla tych wizyt ze strony odsyłającej.
-
visitId
string,
Niepowtarzalny identyfikator tej wizyty.
-
visitTime
Liczba opcjonalnie
Czas wizyty w milisekundach od początku epoki.
Metody
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
Dodaje do historii w bieżącym czasie adres URL z typem przejścia „link”.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
deleteAll()
chrome.history.deleteAll(
callback?: function,
)
Usuwa wszystkie elementy z historii.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
)
Usuwa z historii wszystkie elementy z wybranego zakresu dat. Strony nie zostaną usunięte z historii, chyba że wszystkie wizyty będą się mieścić w tym zakresie.
Parametry
-
zakres
obiekt
-
endTime
Liczba
Elementy dodane do historii przed tą datą, wyrażone w milisekundach od początku epoki.
-
startTime
Liczba
Elementy dodane do historii po tej dacie, wyrażone w milisekundach od początku epoki.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Usuwa z historii wszystkie wystąpienia podanego adresu URL.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Akcje powrotne
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Pobiera informacje o wizytach w adresie URL.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(results: VisitItem[]) => void
-
wyniki
-
Akcje powrotne
-
Promise<VisitItem[]>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
search()
chrome.history.search(
query: object,
callback?: function,
)
Przeszukuje historię ostatnich wizyt każdej strony pasującej do zapytania.
Parametry
-
zapytanie
obiekt
-
endTime
Liczba opcjonalnie
Ogranicz wyniki do odwiedzonych przed tą datą, podaną w milisekundach od początku epoki.
-
maxResults
Liczba opcjonalnie
Maksymalna liczba wyników do pobrania. Domyślna wartość to 100.
-
startTime
Liczba opcjonalnie
Ogranicz wyniki do odwiedzonych po tej dacie, wyrażonych w milisekundach od początku epoki. Jeśli właściwość nie została określona, przyjmuje się domyślnie wartość 24 godziny.
-
plik tekstowy,
string,
Zapytanie tekstowe do usługi historii. Aby pobrać wszystkie strony, pozostaw to pole puste.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(results: HistoryItem[]) => void
-
wyniki
-
Akcje powrotne
-
Promise<HistoryItem[]>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
Uruchamiane po otwarciu adresu URL i dostarcza dane dotyczące tego adresu URL (HistoryItem
). To zdarzenie jest uruchamiane przed wczytaniem strony.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(result: HistoryItem) => void
-
wynik
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
Uruchamiane, gdy co najmniej 1 adres URL zostanie usunięty z historii. Po usunięciu wszystkich wizyt adres URL jest trwale usuwany z historii.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(removed: object) => void
-
usunięto
obiekt
-
allHistory
boolean
Prawda, jeśli cała historia została usunięta. Jeśli ma wartość true, adresy URL będą puste.
-
urls
string[] opcjonalny
-
-