browser.history

Beschreibung

Verwenden Sie die chrome.history API, um mit dem Browserverlauf der besuchten Seiten zu interagieren. Sie können URLs im Browserverlauf hinzufügen, entfernen und abfragen. Informationen zum Überschreiben der Verlaufsseite mit Ihrer eigenen Version 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 ist. Wenn ein Nutzer beispielsweise eine Seite aufruft, indem er auf einen Link auf einer anderen Seite klickt, ist der Übergangstyp „link“. Eine Liste der Übergangstypen finden Sie in den Referenzinhalten.

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Beispiel für die History API 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

    Wann diese Seite zuletzt geladen wurde, dargestellt in Millisekunden seit der Epoche.

  • Titel

    String optional

    Der Titel der Seite, als sie zuletzt geladen wurde.

  • typedCount

    number optional

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

  • URL

    String optional

    Die URL, die ein Nutzer aufgerufen hat.

  • visitCount

    number optional

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

TransitionType

Chrome 44 und höher browser.* seit Chrome 148

Der Übergangstyp für diesen Besuch von seinem Referrer.

Enum

"link"
Der Nutzer ist auf diese Seite gelangt, indem er auf einen Link auf einer anderen Seite geklickt hat.

"typed"
Der Nutzer hat die URL in die Adressleiste eingegeben, um diese Seite aufzurufen. Dies wird auch für andere explizite Navigationsaktionen verwendet.

"auto_bookmark"
Der Nutzer ist über einen Vorschlag in der Benutzeroberfläche auf diese Seite gelangt, z. B. über einen Menüpunkt.

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

"manual_subframe"
Der Nutzer ist auf diese Seite gelangt, indem er etwas in einem Subframe ausgewählt hat.

"generated"
Der Nutzer ist auf diese Seite gelangt, indem er etwas in die Adressleiste eingegeben und einen Eintrag ausgewählt hat, der nicht wie eine URL aussah, z. B. einen Google-Suchvorschlag. Ein Treffer kann beispielsweise die URL einer Google-Suchergebnisseite haben, dem Nutzer aber als „Google-Suche nach…“ angezeigt werden. Diese unterscheiden sich von eingegebenen Navigationsvorgängen, 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 ist auf diese Seite gelangt, indem er Werte in ein Formular eingegeben und das Formular gesendet hat. Nicht alle Formulareinreichungen verwenden diesen Übergangstyp.

"reload"
Der Nutzer hat die Seite aktualisiert, entweder durch Klicken auf die Schaltfläche „Aktualisieren“ oder durch Drücken der Eingabetaste in der Adressleiste. Dieser Übergangstyp wird auch für die Wiederherstellung von Sitzungen und das erneute Öffnen geschlossener Tabs verwendet.

"keyword"
Die URL für diese Seite wurde aus einem ersetzbaren Keyword generiert, das nicht dem Standardsuchanbieter entspricht.

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

UrlDetails

Chrome 88 oder höher browser.* seit Chrome 148

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

    „True“, wenn der Besuch von diesem Gerät ausging. „False“, wenn sie von einem anderen Gerät synchronisiert wurde.

  • referringVisitId

    String

    Die Besuchs-ID des Referrers.

  • Übergang

    TransitionType

    Der Übergangstyp für diesen Besuch von seinem Referrer.

  • visitId

    String

    Die eindeutige Kennung für diesen Besuch.

  • visitTime

    number optional

    Der Zeitpunkt des Besuchs in Millisekunden seit der Epoche.

Methoden

addUrl()

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

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

Parameter

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

deleteAll()

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

Löscht alle Elemente aus dem Verlauf.

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

deleteRange()

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

Entfernt alle Elemente innerhalb des angegebenen Zeitraums aus dem Verlauf. Seiten werden nur dann aus dem Verlauf entfernt, wenn alle Aufrufe in den Zeitraum fallen.

Parameter

  • Angebot

    Objekt

    • endTime

      Zahl

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

    • startTime

      Zahl

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

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

deleteUrl()

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

Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.

Parameter

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

getVisits()

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

Ruft Informationen zu Besuchen einer URL ab.

Parameter

Ausgabe

  • Promise<VisitItem[]>

    Chrome 96+ browser.* seit Chrome 148 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

Sucht im Verlauf nach dem Zeitpunkt des letzten Besuchs jeder Seite, die der Abfrage entspricht.

Parameter

  • Abfrage

    Objekt

    • endTime

      number optional

      Beschränkt die Ergebnisse auf die vor diesem Datum besuchten Seiten, dargestellt in Millisekunden seit der Epoche.

    • maxResults

      number optional

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

    • startTime

      number optional

      Beschränkt die Ergebnisse auf die nach diesem Datum besuchten Ergebnisse, angegeben in Millisekunden seit der Epoche. Wenn das Attribut nicht angegeben ist, wird standardmäßig 24 Stunden verwendet.

    • Text

      String

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

Ausgabe

  • Promise<HistoryItem[]>

    Chrome 96+ browser.* seit Chrome 148

Ereignisse

onVisited

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

Wird ausgelöst, wenn eine URL besucht wird, und 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

browser.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. Wenn „true“, sind die URLs leer.

      • URLs

        string[] optional