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

Plik manifestu

Aby korzystać z interfejsu History API, musisz zadeklarować uprawnienie do „historii” w pliku manifestu rozszerzenia. Przykład:

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

Typy przejść

Interfejs History API używa typu przejścia do opisania sposobu przejścia przeglądarki 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”.

Tabela poniżej zawiera opis poszczególnych typów przejść.

Typ przejściaOpis
"napisano"Użytkownik wyświetlił tę stronę po wpisaniu jej adresu URL w pasku adresu. Używany też do innych działań związanych z nawigacją. Patrz też raport wygenerowane, który jest używany w przypadkach, gdy użytkownik wybrał opcję, która w ogóle nie wygląda jak adres URL.
"auto_bookmark"Użytkownik dotarł na tę stronę dzięki sugestiom w interfejsie, np. pozycji w menu.
"auto_subframe"Nawigacja w ramce podrzędnej. Są to dowolne treści, które są automatycznie wczytywane w ramce spoza najwyższego poziomu. Jeśli np. strona składa się z kilku ramek z reklamami, adresy URL reklam mają ten typ przejścia. Użytkownik może nawet nie zdawać sobie sprawy, że treść tych stron to oddzielna ramka, więc adres URL może nie być dla Ciebie istotny (zobacz również atrybut manual_subframe).
„manual_subframe”Na potrzeby nawigacji ramki podrzędnej o jawne żądanie użytkownika i generowania nowych wpisów nawigacyjnych na liście wstecz/do przodu. Klatka żądana bezpośrednio jest prawdopodobnie ważniejsza niż ramka, która została wczytana automatycznie, ponieważ użytkownikowi prawdopodobnie zależy na tym, że ta ramka została załadowana.
"wygenerowano"Użytkownik dotarł na tę stronę, wpisując na pasku adresu i wybierając wpis, który nie wygląda jak adres URL. Dopasowanie może na przykład zawierać adres URL strony wyników wyszukiwania Google, ale użytkownikowi może wyglądać tak: „Wyszukaj w Google ...”. Są to inne działania niż wpisane elementy nawigacyjne, ponieważ użytkownik nie wpisał lub nie wyświetlił docelowego adresu URL. Zobacz też: keyword.
"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, na przykład gdy treść formularza jest przesyłana za pomocą skryptu, przesłanie formularza nie powoduje zmiany tego rodzaju.
„załaduj ponownie”Użytkownik ponownie załaduje 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.
"słowo kluczowe"Adres URL został wygenerowany na podstawie zamiennego słowa kluczowego innego niż domyślny dostawca wyszukiwania. Zobacz też keyword_generated.
"keyword_generated"Odpowiada wizytom wygenerowanym dla słowa kluczowego. Zobacz też: keyword.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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