refresh date: 2026-09-25 robots: noindex
Opis
Użyj interfejsu API chrome.history, aby wejść w interakcję z rejestrem odwiedzonych stron w przeglądarce. Możesz dodawać, usuwać i wyszukiwać adresy URL w historii przeglądarki. Aby zastąpić stronę historii własną wersją, zapoznaj się z artykułem Zastępowanie stron.
Uprawnienia
historyPlik manifestu
Aby korzystać z interfejsu API historii, musisz zadeklarować uprawnienie „history” w pliku manifestu rozszerzenia. Przykład:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
Typy przejść
Interfejs History API używa typu przejścia, aby opisać, jak przeglądarka przeszła do określonego adresu URL podczas konkretnej wizyty. Jeśli np. użytkownik odwiedzi stronę, klikając link na innej stronie, typem przejścia będzie „link”.
W tabeli poniżej znajdziesz opis każdego typu przejścia.
| Typ przejścia | Opis |
|---|---|
| "link" | Użytkownik trafił na tę stronę, klikając link na innej stronie. |
| "typed" | Użytkownik wszedł na tę stronę, wpisując adres URL na pasku adresu. Służy też do innych działań związanych z nawigacją. Zobacz też generated, który jest używany w przypadkach, gdy użytkownik wybrał opcję, która nie wyglądała jak adres URL. |
| "auto_bookmark" | Użytkownik trafił na tę stronę dzięki sugestii w interfejsie, np. przez element menu. |
| "auto_subframe" | Nawigacja w ramce podrzędnej. Są to dowolne treści, które są automatycznie wczytywane w ramce niebędącej ramką najwyższego poziomu. Jeśli na przykład strona składa się z kilku ramek zawierających reklamy, adresy URL tych reklam mają ten typ przejścia. Użytkownik może nawet nie zdawać sobie sprawy, że treść na tych stronach jest osobną ramką, więc może nie zwracać uwagi na adres URL (patrz też manual_subframe). |
| "manual_subframe" | W przypadku nawigacji w ramkach podrzędnych, które są wyraźnie żądane przez użytkownika i generują nowe wpisy nawigacyjne na liście wstecz/dalej. Ramka, o którą wyraźnie poproszono, jest prawdopodobnie ważniejsza niż ramka wczytywana automatycznie, ponieważ użytkownikowi prawdopodobnie zależy na tym, aby została ona wczytana. |
| "generated" | Użytkownik wszedł na tę stronę, wpisując tekst na pasku adresu i wybierając wpis, który nie wyglądał jak adres URL. Na przykład dopasowanie może mieć adres URL strony wyników wyszukiwania Google, ale użytkownikowi może się wyświetlać jako „Wyszukaj w Google…”. Nie jest to dokładnie to samo co nawigacja wpisana, ponieważ użytkownik nie wpisał ani nie widział docelowego adresu URL. Zobacz też słowo kluczowe. |
| "auto_toplevel" | Strona została określona w wierszu poleceń lub jest stroną startową. |
| "form_submit" | Użytkownik wypełnił wartości w formularzu i go przesłał. Pamiętaj, że w niektórych sytuacjach (np. gdy formularz używa skryptu do przesyłania treści) przesłanie formularza nie powoduje tego typu przejścia. |
| „reload” | Użytkownik ponownie załadował stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Ten typ przejścia jest też używany w przypadku przywracania sesji i ponownego otwierania zamkniętej karty. |
| "słowo kluczowe" | Adres URL został wygenerowany na podstawie słowa kluczowego, które można zastąpić, innego niż domyślny dostawca wyszukiwania. Zobacz też keyword_generated. |
| "keyword_generated" | Odpowiada wizycie wygenerowanej dla słowa kluczowego. Zobacz też słowo kluczowe. |
Przykłady
Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu API historii z repozytorium chrome-extension-samples.
Typy
HistoryItem
Obiekt zawierający 1 wynik zapytania dotyczącego historii.
Właściwości
-
id
tekst
Unikalny identyfikator elementu.
-
lastVisitTime
number optional
Czas ostatniego wczytania tej strony, wyrażony w milisekundach od początku epoki.
-
tytuł
ciąg znaków opcjonalny
Tytuł strony podczas jej ostatniego wczytywania.
-
typedCount
number optional
Liczba przypadków, gdy użytkownik przeszedł na tę stronę, wpisując adres.
-
URL
ciąg znaków opcjonalny
Adres URL, który odwiedził użytkownik.
-
visitCount
number optional
Liczba wizyt użytkownika na tej stronie.
Typ wyliczeniowy
"link"
Użytkownik trafił na tę stronę, klikając link na innej stronie.
"typed"
Użytkownik trafił na tę stronę, wpisując adres URL na pasku adresu. Jest on też używany do innych działań związanych z nawigacją.
"auto_bookmark"
Użytkownik trafił na tę stronę dzięki sugestii w interfejsie, np. przez element menu.
"auto_subframe"
Użytkownik trafił na tę stronę przez nawigację w ramce podrzędnej, której nie żądał, np. przez wczytywanie reklam 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ę, wpisując tekst na pasku adresu i wybierając wpis, który nie wyglądał jak adres URL, np. sugestię wyszukiwania Google. Na przykład dopasowanie może mieć adres URL strony wyników wyszukiwania Google, ale użytkownikowi może się wyświetlać jako „Wyszukaj w Google…”. Różni się to od wpisanych adresów, ponieważ użytkownik nie wpisał ani nie widział docelowego adresu URL. Są też powiązane z nawigacją po słowach kluczowych.
"auto_toplevel"
Strona została określona w wierszu poleceń lub jest stroną startową.
"form_submit"
Użytkownik trafił na tę stronę, wypełniając i przesyłając formularz. Nie wszystkie przesłane formularze używają tego typu przejścia.
"reload"
Użytkownik ponownie załadował stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Ten typ przejścia jest też używany podczas przywracania sesji i ponownego otwierania zamkniętej karty.
"keyword"
Adres URL tej strony został wygenerowany na podstawie zastępowalnego słowa kluczowego innego niż domyślny dostawca wyszukiwania.
"keyword_generated"
Odpowiada wizycie wygenerowanej dla słowa kluczowego.
UrlDetails
Właściwości
-
URL
tekst
Adres URL operacji. Musi mieć format zwracany przez wywołanie
history.search().
VisitItem
Obiekt zawierający informacje o jednej wizycie pod adresem URL.
Właściwości
-
id
tekst
Unikalny identyfikator odpowiedniego
history.HistoryItem. -
isLocal
wartość logiczna
Chrome 115 lub nowsza wersjaPrawda, jeśli wizyta została rozpoczęta na tym urządzeniu. Wartość „false”, jeśli został zsynchronizowany z innego urządzenia.
-
referringVisitId
tekst
Identyfikator wizyty strony odsyłającej.
-
przejście
Typ przejścia do tej wizyty z witryny odsyłającej.
-
visitId
tekst
Unikalny identyfikator tej wizyty.
-
visitTime
number optional
Czas wizyty wyrażony w milisekundach od początku epoki.
Metody
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
Dodaje adres URL do historii w bieżącym czasie z typem przejścia „link”.
Parametry
-
szczegóły
-
callback
function opcjonalne
Parametr
callbackwygląda tak:() => void
Zwroty
-
thought Promise<void>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
deleteAll()
chrome.history.deleteAll(
callback?: function,
): Promise<void>
Usuwa wszystkie elementy z historii.
Parametry
-
callback
function opcjonalne
Parametr
callbackwygląda tak:() => void
Zwroty
-
thought Promise<void>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
): Promise<void>
Usuwa z historii wszystkie elementy z określonego zakresu dat. Strony nie zostaną usunięte z historii, chyba że wszystkie wizyty mieszczą się w tym zakresie.
Parametry
-
zakres
obiekt
-
endTime
liczba
Elementy dodane do historii przed tą datą, podane w milisekundach od początku epoki.
-
startTime
liczba
Elementy dodane do historii po tej dacie, wyrażone w milisekundach od początku epoki.
-
-
callback
function opcjonalne
Parametr
callbackwygląda tak:() => void
Zwroty
-
thought Promise<void>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
Usuwa z historii wszystkie wystąpienia danego adresu URL.
Parametry
-
szczegóły
-
callback
function opcjonalne
Parametr
callbackwygląda tak:() => void
Zwroty
-
thought Promise<void>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
): Promise<VisitItem[]>
Pobiera informacje o wizytach pod adresem URL.
Parametry
-
szczegóły
-
callback
function opcjonalne
Parametr
callbackwygląda tak:(results: VisitItem[]) => void
-
wyniki
-
Zwroty
-
Promise<VisitItem[]>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
search()
chrome.history.search(
query: object,
callback?: function,
): Promise<HistoryItem[]>
Przeszukuje historię pod kątem czasu ostatniej wizyty na każdej stronie pasującej do zapytania.
Parametry
-
zapytanie
obiekt
-
endTime
number optional
Ogranicz wyniki do tych odwiedzonych przed tą datą, wyrażoną w milisekundach od początku epoki.
-
maxResults
number optional
Maksymalna liczba wyników do pobrania. Domyślna wartość to 100.
-
startTime
number optional
Ogranicz wyniki do tych, które zostały odwiedzone po tej dacie, wyrażonej w milisekundach od początku epoki. Jeśli nie określisz tej właściwości, domyślnie zostanie ustawiona wartość 24 godziny.
-
tekst
tekst
Zapytanie w formie tekstu swobodnego do usługi historii. Pozostaw to pole puste, aby pobrać wszystkie strony.
-
-
callback
function opcjonalne
Parametr
callbackwygląda tak:(results: HistoryItem[]) => void
-
wyniki
-
Zwroty
-
Promise<HistoryItem[]>
Chrome 96 lub nowsza wersjaObiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.
Wydarzenia
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
Uruchamiane, gdy użytkownik odwiedza adres URL, i dostarczające dane HistoryItem dla tego adresu URL. To zdarzenie jest wywoływane przed wczytaniem strony.
Parametry
-
callback
funkcja
Parametr
callbackwyglą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. Gdy wszystkie wizyty zostaną usunięte, adres URL zostanie usunięty z historii.
Parametry
-
callback
funkcja
Parametr
callbackwygląda tak:(removed: object) => void
-
usunięto
obiekt
-
allHistory
wartość logiczna
Wartość „Prawda”, jeśli cała historia została usunięta. Jeśli ma wartość „true”, adresy URL będą puste.
-
adresy
string[] opcjonalne
-
-