browser.history

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

history

Aby 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 użycie

Typy przejść

Interfejs History API używa typów przejść, aby opisać, jak przeglądarka przeszła do określonego adresu URL podczas danej wizyty. Jeśli np. użytkownik odwiedzi stronę, klikając link na innej stronie, typem przejścia będzie „link”. Listę typów przejść znajdziesz w materiałach referencyjnych.

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.

TransitionType

Chrome 44 lub nowsza browser.* od Chrome 148

Typ przejścia do tej wizyty z witryny odsyłającej.

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

Chrome 88 lub nowsza browser.* od Chrome 148

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 browser.* od Chrome 148

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

    TransitionType

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

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

Parametry

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

deleteAll()

browser.history.deleteAll(): Promise<void>

Usuwa wszystkie elementy z historii.

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

deleteRange()

browser.history.deleteRange(
  range: object,
): 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.

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

Usuwa z historii wszystkie wystąpienia danego adresu URL.

Parametry

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

Pobiera informacje o wizytach pod adresem URL.

Parametry

Zwroty

  • Promise<VisitItem[]>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148 
browser.history.search(
  query: object,
): 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.

Zwroty

  • Promise<HistoryItem[]>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

Wydarzenia

onVisited

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

onVisitRemoved

browser.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 callback wyglą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