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

Aby wejść w interakcję z historią przeglądania użytkownika, użyj interfejsu History API.

Aby używać interfejsu History API, zadeklaruj uprawnienia "history" w pliku manifestu rozszerzenia. Przykład:

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

Pojęcia i wykorzystanie

Typy przejść

Interfejs History API wykorzystuje typy przejść, aby opisać, jak przeglądarka przeszedła 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”. Listę tych kwestii znajdziesz w materiałach referencyjnych. typy przejść.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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