chrome.history

Opis

Użyj interfejsu chrome.history API, aby korzystać z historii odwiedzonych stron w przeglądarce. Możesz dodawać i usuwać adresy URL w historii przeglądarki oraz wyszukiwać je. Aby zastąpić stronę historii własną wersją, zapoznaj się z sekcją Zastępowanie stron.

Uprawnienia

history

Plik manifestu

Aby korzystać z interfejsu history API, 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, typ przejścia to „link”.

W tabeli poniżej opisujemy poszczególne typy przejść.

Typ przejściaOpis
„typed”Użytkownik otworzył tę stronę, wpisując adres URL na pasku adresu. Używane też w przypadku innych działań związanych z wyraźną nawigacją. Zobacz też generated, które jest używane w przypadku, gdy użytkownik wybrał opcję, która w ogóle nie przypominała adresu URL.
„auto_bookmark”Użytkownik trafił na tę stronę dzięki sugestii w interfejsie, np. za pomocą elementu menu.
„auto_subframe”Nawigacja po ramkach podrzędnych. Są to treści, które są automatycznie wczytywane w ramce nie 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ą, i dlatego nie będzie zwracać uwagi na adres URL (zobacz też manual_subframe).
„manual_subframe”W przypadku nawigacji w ramce podrzędnej, o którą użytkownik wyraźnie poprosił i która generuje nowe wpisy nawigacji na liście wstecz/dalej. Wyraźnie zażądana ramka jest prawdopodobnie ważniejsza niż ramka załadowana automatycznie, ponieważ użytkownikowi zależy na tym, aby załadowana została ramka, o którą poprosił.
„wygenerowane”Użytkownik otworzył tę stronę, wpisując coś w pasku adresu i wybierając wpis, który nie wyglądał jak adres URL. Na przykład dopasowanie może zawierać adres URL strony wyników wyszukiwania Google, ale użytkownikowi może się wyświetlać jako „Wyszukaj w Google…”. Nie są to do końca nawigacje wpisane, ponieważ użytkownik nie wpisał ani nie zobaczył 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ł formularz 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 zastępowalnego słowa kluczowego 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 jeden wynik zapytania dotyczącego historii.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator elementu.

  • lastVisitTime

    number opcjonalny

    Czas ostatniego wczytania tej strony w milisekundach od początku epoki.

  • tytuł

    string opcjonalny

    Tytuł strony w momencie ostatniego wczytania.

  • typedCount

    number opcjonalny

    Liczba wizyt użytkownika na tej stronie po wpisaniu adresu.

  • URL

    string opcjonalny

    Adres URL, na który przechodzi użytkownik.

  • visitCount

    number opcjonalny

    Liczba przypadków, w których użytkownik przeszedł na tę stronę.

TransitionType

Chrome 44 lub nowszy

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

Typ wyliczeniowy

„link”
Użytkownik dotarł na tę stronę, klikając link na innej stronie.

„typed”
Użytkownik otworzył tę stronę, wpisując adres URL na pasku adresu. Jest on też używany w przypadku innych działań związanych z wyraźną nawigacją.

„auto_bookmark”
Użytkownik trafił na tę stronę dzięki sugestii w interfejsie, np. elementowi menu.

„auto_subframe”
Użytkownik trafił na tę stronę w wyniku nawigacji w ramce podrzędnej, której nie zainicjował, np. w wyniku wczytania reklamy w ramce na poprzedniej stronie. Nie zawsze generują one nowe wpisy w menu Wstecz i Dalej.

„manual_subframe”
Użytkownik dotarł na tę stronę, wybierając coś w ramce podrzędnej.

„generated”
Użytkownik dotarł na tę stronę, wpisując adres w pasku adresu i wybierając wpis, który nie wyglądał jak adres URL, np. sugestię wyszukiwarki Google. Na przykład dopasowanie może zawierać adres URL strony wyników wyszukiwania Google, ale użytkownik może widzieć je jako „Wyszukaj w Google…”. Różni się to od wpisywanych nawigacji, ponieważ użytkownik nie wpisał ani nie zobaczył docelowego adresu URL. Są one też powiązane z nawigacją za pomocą słów 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 ponownie załadował stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Przywracanie sesji i ponowne otwieranie zamkniętej karty również korzystają z tego typu przejścia.

„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

Właściwości

  • URL

    ciąg znaków

    Adres URL operacji. Musi mieć format zwrócony przez wywołanie funkcji history.search().

VisitItem

Obiekt zawierający jedną wizytę pod adresem URL.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator odpowiedniego history.HistoryItem.

  • isLocal

    Wartość logiczna

    Chrome 115 lub nowsza

    Wartość Prawda, jeśli wizyta pochodzi z tego urządzenia. Fałsz, jeśli został zsynchronizowany z innego urządzenia.

  • referringVisitId

    ciąg znaków

    Identyfikator wizyty strony odsyłającej.

  • przejście,

    TransitionType

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

  • visitId

    ciąg znaków

    Unikalny identyfikator tej wizyty.

  • visitTime

    number opcjonalny

    Czas wystąpienia wizyty w milisekundach od początku epoki.

Metody

addUrl()

Obietnica 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Parametry

  • szczegóły

    UrlDetails

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

deleteAll()

Obietnica 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

Usuwa wszystkie elementy z historii.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

deleteRange()

Obietnica 
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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

deleteUrl()

Obietnica 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

Usuwa z historii wszystkie wystąpienia danego adresu URL.

Parametry

  • szczegóły

    UrlDetails

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getVisits()

Obietnica 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

Pobiera informacje o wizytach pod adresem URL.

Parametry

Zwroty

  • Promise<VisitItem[]>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Obietnica 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

Przeszukuje historię, aby znaleźć czas ostatniej wizyty na każdej stronie pasującej do zapytania.

Parametry

  • zapytanie

    obiekt

    • endTime

      number opcjonalny

      Ogranicz wyniki do tych, które zostały odwiedzone przed tą datą (w milisekundach od początku epoki).

    • maxResults

      number opcjonalny

      Maksymalna liczba wyników do pobrania. Domyślna wartość to 100.

    • startTime

      number opcjonalny

      Ogranicz wyniki do tych, które zostały odwiedzone po tej dacie (w milisekundach od początku epoki). Jeśli nie określisz tej właściwości, domyślnie będzie to 24 godziny.

    • tekst

      ciąg znaków

      Zapytanie z dowolnym tekstem do usługi historii. Aby pobrać wszystkie strony, pozostaw to pole puste.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (results: HistoryItem[]) => void

Zwroty

  • Promise<HistoryItem[]>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

Uruchamiane, gdy odwiedzany jest adres URL, i zawiera HistoryItem dane dotyczące tego adresu. To zdarzenie jest wywoływane przed wczytaniem strony.

Parametry

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

Uruchamia się, gdy z historii zostanie usunięty co najmniej 1 adres URL. Gdy wszystkie wizyty zostaną usunięte, adres URL zostanie wyczyszczony 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