chrome.history

Beschreibung

Verwenden Sie die chrome.history API, um mit dem Browserverlauf zu interagieren. Sie können URLs im Browserverlauf hinzufügen, entfernen und abfragen. Informationen dazu, wie Sie die Verlaufsseite mit Ihrer eigenen Version überschreiben, finden Sie unter Seiten überschreiben.

Berechtigungen

history

Verwenden Sie die History API, um mit dem Browserverlauf des Nutzers zu interagieren.

Wenn Sie die History API verwenden möchten, deklarieren Sie die Berechtigung "history" im Erweiterungsmanifest. Beispiel:

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

Konzepte und Verwendung

Übergangstypen

Die History API verwendet Übergangstypen, um zu beschreiben, wie der Browser bei einem bestimmten Besuch zu einer bestimmten URL navigiert hat. Wenn ein Nutzer beispielsweise eine Seite aufruft, indem er auf einer anderen Seite auf einen Link klickt, ist der Übergangstyp „link“. Eine Liste der Übergangstypen finden Sie unter Referenzinhalte.

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das History API-Beispiel aus dem Repository chrome-extension-samples.

Typen

HistoryItem

Ein Objekt, das ein Ergebnis einer Verlaufsabfrage kapselt.

Attribute

  • id

    String

    Die eindeutige Kennung für den Artikel.

  • lastVisitTime

    number optional

    Zeitpunkt des letzten Ladens dieser Seite in Millisekunden seit der Epoche.

  • Titel

    String optional

    Der Titel der Seite, als sie zuletzt geladen wurde.

  • typedCount

    number optional

    Dieser Wert gibt an, wie oft der Nutzer die Adresse eingegeben hat, um diese Seite aufzurufen.

  • URL

    String optional

    Die URL, die ein Nutzer aufruft.

  • visitCount

    number optional

    Gibt an, wie oft der Nutzer diese Seite aufgerufen hat.

TransitionType

Chrome 44 und höher

Der Übergangstyp für diesen Besuch vom Referrer.

Enum

„Link“
Der Nutzer hat diese Seite aufgerufen, indem er auf einer anderen Seite auf einen Link geklickt hat.

„typed“
Der Nutzer hat die URL in die Adressleiste eingegeben, um auf diese Seite zu gelangen. Dies wird auch für andere explizite Navigationsaktionen verwendet.

„auto_bookmark“
Der Nutzer hat diese Seite über einen Vorschlag in der Benutzeroberfläche aufgerufen, z. B. über ein Menüelement.

auto_subframe
Der Nutzer hat diese Seite über die Subframe-Navigation aufgerufen, die er nicht angefordert hat, z. B. über eine Anzeige, die in einem Frame auf der vorherigen Seite geladen wurde. Dadurch werden nicht immer neue Navigationseinträge in den Menüs „Zurück“ und „Vorwärts“ generiert.

„manual_subframe“
Der Nutzer hat diese Seite aufgerufen, indem er etwas in einem untergeordneten Frame ausgewählt hat.

generiert
Der Nutzer hat diese Seite aufgerufen, indem er in die Adressleiste getippt und einen Eintrag ausgewählt hat, der nicht wie eine URL aussah, z. B. einen Vorschlag aus der Google Suche. Ein Beispiel: Ein Treffer kann die URL einer Google-Suchergebnisseite enthalten, wird dem Nutzer aber möglicherweise als „Suche bei Google nach …“ angezeigt. Diese unterscheiden sich von eingegebenen Navigationsanfragen, da der Nutzer die Ziel-URL nicht eingegeben oder gesehen hat. Sie hängen auch mit der Keyword-Navigation zusammen.

„auto_toplevel“
Die Seite wurde in der Befehlszeile angegeben oder ist die Startseite.

„form_submit“
Der Nutzer hat diese Seite aufgerufen, nachdem er Werte in ein Formular eingegeben und das Formular gesendet hat. Nicht alle Formulareinsendungen verwenden diesen Übergangstyp.

„reload“
Der Nutzer hat die Seite neu geladen, entweder durch Klicken auf die Schaltfläche zum Neuladen oder durch Drücken der Eingabetaste in der Adressleiste. Auch die Funktionen „Sitzung wiederherstellen“ und „Geschlossenen Tab wieder öffnen“ verwenden diesen Übergangstyp.

„keyword“
Die URL für diese Seite wurde aus einem Platzhalter-Keyword generiert, das nicht der Standardsuchanbieter ist.

„keyword_generated“
Entspricht einem Besuch, der für ein Keyword generiert wurde.

UrlDetails

Chrome 88 und höher

Attribute

  • URL

    String

    Die URL für den Vorgang. Sie muss das Format haben, das von einem Aufruf von history.search() zurückgegeben wird.

VisitItem

Ein Objekt, das einen Besuch einer URL kapselt.

Attribute

  • id

    String

    Die eindeutige Kennung für die entsprechende history.HistoryItem.

  • isLocal

    boolean

    Chrome 115 und höher

    „True“, wenn der Besuch auf diesem Gerät erfolgt ist. „False“, wenn die Synchronisierung von einem anderen Gerät aus erfolgte.

  • referringVisitId

    String

    Die Besuchs-ID des Referrers.

  • Übergang

    TransitionType

    Der Übergangstyp für diesen Besuch vom Referrer.

  • visitId

    String

    Die eindeutige Kennung für diesen Besuch.

  • visitTime

    number optional

    Der Zeitpunkt des Besuchs in Millisekunden seit der Epoche.

Methoden

addUrl()

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

Fügt dem Verlauf eine URL mit dem Übergangstyp „link“ hinzu.

Parameter

Ausgabe

  • Promise<void>

    Chrome 96 und höher

deleteAll()

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

Löscht alle Elemente aus dem Verlauf.

Ausgabe

  • Promise<void>

    Chrome 96 und höher

deleteRange()

chrome.history.deleteRange(
  range: object,
): Promise<void>

Entfernt alle Elemente im angegebenen Zeitraum aus dem Verlauf. Seiten werden nur dann aus dem Verlauf entfernt, wenn alle Besuche in den angegebenen Zeitraum fallen.

Parameter

  • Angebot

    Objekt

    • endTime

      Zahl

      Elemente, die vor diesem Datum dem Verlauf hinzugefügt wurden, in Millisekunden seit der Epoche.

    • startTime

      Zahl

      Elemente, die dem Verlauf nach diesem Datum hinzugefügt wurden, in Millisekunden seit der Epoche.

Ausgabe

  • Promise<void>

    Chrome 96 und höher

deleteUrl()

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

Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.

Parameter

Ausgabe

  • Promise<void>

    Chrome 96 und höher

getVisits()

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

Ruft Informationen zu Besuchen einer URL ab.

Parameter

Ausgabe

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

Sucht im Verlauf nach der letzten Besuchszeit jeder Seite, die der Anfrage entspricht.

Parameter

  • Abfrage

    Objekt

    • endTime

      number optional

      Ergebnisse auf Orte beschränken, die vor diesem Datum besucht wurden. Das Datum wird in Millisekunden seit der Epoche angegeben.

    • maxResults

      number optional

      Die maximale Anzahl der abzurufenden Ergebnisse. Die Standardeinstellung ist 100.

    • startTime

      number optional

      Ergebnisse auf Besuche nach diesem Datum beschränken, angegeben in Millisekunden seit der Epoche. Wenn die Eigenschaft nicht angegeben ist, beträgt der Standardwert 24 Stunden.

    • Text

      String

      Eine Freitextabfrage an den Verlaufsdienst. Lassen Sie dieses Feld leer, um alle Seiten abzurufen.

Ausgabe

Ereignisse

onVisited

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

Wird ausgelöst, wenn eine URL aufgerufen wird. Stellt die HistoryItem-Daten für diese URL bereit. Dieses Ereignis wird ausgelöst, bevor die Seite geladen wurde.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (result: HistoryItem) => void

onVisitRemoved

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

Wird ausgelöst, wenn eine oder mehrere URLs aus dem Verlauf entfernt werden. Wenn alle Besuche entfernt wurden, wird die URL aus dem Verlauf gelöscht.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (removed: object) => void

    • entfernt

      Objekt

      • allHistory

        boolean

        Wahr, wenn der gesamte Verlauf entfernt wurde. Bei „true“ sind die URLs leer.

      • URLs

        string[] optional