chrome.history

Opis

Do interakcji z rejestrem odwiedzonych stron w przeglądarce należy używać interfejsu API chrome.history. W historii przeglądarki możesz dodawać i usuwać adresy URL, a także wysyłać dotyczące ich zapytania. Aby zastąpić stronę historii własną wersją, przeczytaj sekcję Zastąp strony.

Uprawnienia

history

Plik manifestu

Musisz zadeklarować historię uprawnienia w pliku manifestu rozszerzenia na korzystanie z interfejsu API historii. Przykład:

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

Typy przejść

Interfejs History API wykorzystuje typ przejścia do opisania, w jaki sposób przeglądarka przekierowała przeglądarkę do określonego adresu URL. podczas konkretnej wizyty. Jeśli na przykład użytkownik odwiedzi stronę, klikając link na innej stronie, parametr typu przejścia to „link”.

W tabeli poniżej opisujemy różne typy przejścia.

Typ przejściaOpis
"typed"Użytkownik otrzymał tę stronę, wpisując adres URL w pasku adresu. Służy też do innych działań związanych z nawigacją. Zobacz też artykuł Wygenerowane. Atrybut ten jest używany w przypadkach, gdy użytkownik wybrał odpowiedź, która nie wygląda jak adres URL.
„auto_bookmark”Użytkownik dostał tę stronę dzięki sugestii w interfejsie, np. pozycji menu.
„auto_subframe”Nawigacja z ramką podrzędną. Są to wszystkie treści, które są automatycznie wczytywane w ramce spoza najwyższego poziomu. Jeśli np. strona składa się z kilku ramek zawierających reklamy, w tych adresach URL reklam występuje ten typ przejścia. Użytkownik może nawet nie zdawać sobie sprawy, że zawartość tych stron jest w oddzielnej ramce, więc adres URL może nie być ważny (zobacz też manual_subframe).
„manual_subframe”,Dotyczy nawigacji w ramce podrzędnej, na które użytkownik jawnie prosi i generuje nowe wpisy nawigacyjne na liście wstecz/dalej. Wyraźnie żądana ramka jest prawdopodobnie ważniejsza niż ramka ładowana automatycznie, ponieważ użytkownik prawdopodobnie interesuje się tym, że żądana ramka została załadowana.
"wygenerowano"Użytkownik dotarł na tę stronę, wpisując tekst w 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 być wyświetlany jako „Szukaj w Google ...”. Nie różnią się one od opcji nawigacyjnych wpisanych, ponieważ użytkownik nie wpisał lub nie widział docelowego adresu URL. Zobacz też słowo kluczowe.
„auto_najwyższy poziom”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 przekazywana za pomocą skryptu, przesłanie formularza nie powoduje zastosowania takiego przejścia.
„załaduj ponownie”Użytkownik załaduje ponownie stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Tego typu przejścia używają także przywracanie sesji i ponowne otwarcie zamkniętej karty.
"słowo kluczowe"Adres URL został wygenerowany na podstawie wymiennego słowa kluczowego innego niż domyślny dostawca wyszukiwania. Zobacz też parametr keyword_generated.
„keyword_wygenerowane”Odpowiada odwiedzinom wygenerowanym dla słowa kluczowego. Zobacz też słowo kluczowe.

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs API historii ze strony chrome-extension-samples z repozytorium.

Typy

HistoryItem

Obiekt zawierający 1 wynik zapytania dotyczącego historii.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator produktu.

  • lastVisitTime

    liczba opcjonalnie

    Czas ostatniego wczytania strony, wyrażony w milisekundach od początku epoki.

  • tytuł

    ciąg znaków opcjonalny

    Tytuł strony podczas jej ostatniego wczytywania.

  • typedCount

    liczba opcjonalnie

    Ile razy użytkownik przeszedł na tę stronę, wpisując adres.

  • URL

    ciąg znaków opcjonalny

    Adres URL, do którego przeszedł użytkownik.

  • visitCount

    liczba opcjonalnie

    Liczba wejść użytkownika na tę stronę.

TransitionType

Chrome w wersji 44 lub nowszej .

Typ przejścia tej wizyty ze strony odsyłającej.

Typ wyliczeniowy

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

"typed"
Użytkownik dotarł na tę stronę, wpisując URL na pasku adresu. Jest też używana w innych działaniach związanych z nawigacją.

"auto_bookmark"
Użytkownik dotarł na tę stronę dzięki sugestiom w interfejsie, np. po kliknięciu pozycji menu.

"auto_subframe"
Użytkownik wyświetlił tę stronę przez nawigację w ramce podrzędnej, której nie chciał, np. przez reklamę wczytaną w ramce na poprzedniej stronie. Nie zawsze generują nowe pozycje nawigacyjne w menu wstecz i dalej.

"manual_subframe"
Użytkownik wyświetlił tę stronę, wybierając coś w ramce podrzędnej.

"generate"
Użytkownik dotarł na tę stronę, wpisując w pasku adresu i wybierając wpis, który nie wygląda jak URL (np. sugestia wyszukiwarki 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ę one od wpisywanych nawigacji, ponieważ użytkownik nie wpisał lub nie widział docelowego adresu URL. Są one również zwią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 dotarł na tę stronę, wypełniając wartości w formularzu i przesyłając formularz. Nie wszystkie przesłane formularze używają tego typu przejścia.

"reload"
Użytkownik ponownie załaduje stronę, klikając przycisk ponownego załadowania lub naciskając Enter na pasku adresu. Tego typu przejścia używają również przywracanie sesji i ponownie otwarte karty.

"keyword"
Adres URL tej strony został wygenerowany na podstawie wymiennego słowa kluczowego innego niż domyślny dostawca wyszukiwania.

"keyword_generate"
odpowiada wizytom wygenerowanym dla słowa kluczowego.

UrlDetails

Chrome 88 i nowsze .

Właściwości

  • URL

    ciąg znaków

    Adres URL operacji. Musi mieć format zwrócony z wywołania history.search().

VisitItem

Obiekt zawierający jedne odwiedziny adresu URL.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator odpowiedniego elementu history.HistoryItem.

  • isLocal

    wartość logiczna

    Chrome w wersji 115 lub nowszej .

    Prawda, jeśli wizyta pochodzi z tego urządzenia. Wartość false, jeśli została zsynchronizowana z innego urządzenia.

  • referringVisitId

    ciąg znaków

    Identyfikator wizyty strony odsyłającej.

  • przejście

    TransitionType

    Typ przejścia tej wizyty ze strony odsyłającej.

  • visitId

    ciąg znaków

    Unikalny identyfikator tej wizyty.

  • visitTime

    liczba opcjonalnie

    Czas wystąpienia tej wizyty (wyrażony w milisekundach od początku epoki).

Metody

addUrl()

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

Dodaje do historii aktualny adres URL z typem przejścia „link”.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, 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 optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

deleteRange()

Obietnica .
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

Usuwa z historii wszystkie elementy w wybranym zakresie dat. Strony nie zostaną usunięte z historii, chyba że wszystkie wizyty mieszczą się w 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 optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

deleteUrl()

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

Usuwa z historii wszystkie wystąpienia danego adresu URL.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getVisits()

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

Pobiera informacje o wizytach pod adresem URL.

Parametry

  • szczegóły

    UrlDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (results: VisitItem[]) => void

Zwroty

  • Promise&lt;VisitItem[]&gt;

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

Obietnica .
chrome.history.search(
  query: object,
  callback?: function,
)

Przeszukuje historię pod kątem czasu ostatniej wizyty na każdej stronie pasującej do zapytania.

Parametry

  • zapytanie

    Obiekt

    • endTime

      liczba opcjonalnie

      Ogranicz wyniki do tych odwiedzonych przed tą datą, wyrażonych 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 tych odwiedzonych po tej dacie, wyrażonych w milisekundach od początku epoki. Jeśli właściwość nie zostanie określona, zostanie użyta domyślna wartość 24 godziny.

    • tekst

      ciąg znaków

      Zapytanie tekstowe kierowane do usługi historii. Pozostaw to pole puste, aby pobrać wszystkie strony.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (results: HistoryItem[]) => void

Zwroty

  • Promise&lt;HistoryItem[]&gt;

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onVisited

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

Uruchamiane po odwiedzeniu adresu URL i dostarcza dane HistoryItem dotyczące tego adresu URL. To zdarzenie jest uruchamiane przed wczytaniem strony.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (result: HistoryItem) => void

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 usuwany z historii.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (removed: object) => void

    • usunięto

      Obiekt

      • allHistory

        wartość logiczna

        Prawda, jeśli cała historia została usunięta. Jeśli ma wartość true (prawda), adresy URL będą puste.

      • adresy

        string[] opcjonalnie