chrome.history

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.

TransitionType

Chrome 44 i nowsze wersje

Typ przejścia dla tych wizyt ze strony odsyłającej.

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

Chrome 88 i nowsze wersje

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 wersje

    Prawda, 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

    TransitionType

    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()

Obietnica 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Dodaje do historii w bieżącym czasie adres URL z typem przejścia „link”.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 96 i nowsze wersje

    Obietnice 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()

Obietnica 
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 wersje

    Obietnice 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()

Obietnica 
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 wersje

    Obietnice 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()

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

Usuwa z historii wszystkie wystąpienia podanego adresu URL.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 96 i nowsze wersje

    Obietnice 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()

Obietnica 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Pobiera informacje o wizytach w adresie URL.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (results: VisitItem[])=>void

Akcje powrotne

  • Promise<VisitItem[]>

    Chrome 96 i nowsze wersje

    Obietnice 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.

Obietnica 
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

Akcje powrotne

  • Promise<HistoryItem[]>

    Chrome 96 i nowsze wersje

    Obietnice 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

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