chrome.history

Beschreibung

Verwenden Sie die chrome.history API, um mit dem Datensatz der besuchten Seiten im Browser 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.

Damit Sie die History API verwenden können, müssen Sie die Berechtigung "history" im Erweiterungsmanifest deklarieren. Beispiel:

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

Konzepte und Nutzung

Ü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 durch Klicken auf einen Link auf einer anderen Seite aufruft, lautet der Übergangstyp „Link“. Eine Liste der Übergangstypen finden Sie im Referenzinhalt.

Beispiele

Wenn Sie diese API testen möchten, installieren Sie das history API-Beispiel aus dem Repository chrome-extension-sample.

Typen

HistoryItem

Ein Objekt, das ein Ergebnis einer Verlaufsabfrage enthält.

Attribute

  • id

    String

    Die eindeutige Kennzeichnung für den Artikel.

  • lastVisitTime

    Nummer optional

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

  • Titel

    String optional

    Der Titel der Seite, als sie zuletzt geladen wurde.

  • typedCount

    Nummer optional

    Gibt an, wie oft der Nutzer durch Eingabe der Adresse zu dieser Seite gelangt ist.

  • url

    String optional

    Die URL, die ein Nutzer aufgerufen hat.

  • visitCount

    Nummer optional

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

TransitionType

Chrome 44 und höher

Der Übergangstyp für diesen Besuch von der Verweis-URL.

Enum

"link"
Der Nutzer ist über einen Link auf einer anderen Seite auf diese Seite gelangt.

"Tippen"
Der Nutzer kam durch Eingabe der URL in die Adressleiste auf diese Seite. Sie 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 auf diese Seite gelangt, die er nicht angefordert hat, beispielsweise weil eine Anzeige in einem Frame auf der vorherigen Seite geladen wurde. Dadurch werden nicht immer neue Navigationseinträge in den Menüs „Zurück“ und „Weiter“ generiert.

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

"Generiert"
Der Nutzer ist auf diese Seite gelangt, indem er einen Text in die Adressleiste eingegeben und einen Eintrag ausgewählt hat, der nicht wie eine URL aussieht, z. B. einen Vorschlag in der Google Suche. Eine Übereinstimmung kann beispielsweise die URL einer Google-Suchergebnisseite enthalten, dem Nutzer aber möglicherweise als „Mit Google suchen nach ...“ angezeigt werden. Diese unterscheiden sich von der eingegebenen Navigation, da der Nutzer die Ziel-URL nicht eingegeben oder diese nicht gesehen hat. Sie haben auch einen Bezug zur Keyword-Navigation.

"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 ausgefüllt und das Formular gesendet hat. Diese Übergangsart wird nicht für alle Formulareinreichungen verwendet.

"reload"
Der Nutzer hat die Seite neu geladen, entweder durch Klicken auf die Schaltfläche zum Aktualisieren oder durch Drücken der Eingabetaste in der Adressleiste. Für die Sitzungswiederherstellung und das Öffnen eines geschlossenen Tabs wird ebenfalls dieser Übergangstyp verwendet.

"keyword"
Die URL dieser Seite wurde aus einem anderen austauschbaren Suchbegriff als dem Standardsuchanbieter generiert.

"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. Er muss in dem Format vorliegen, das von einem Aufruf von history.search() zurückgegeben wurde.

VisitItem

Ein Objekt, das einen Besuch einer URL einschließt.

Attribute

  • id

    String

    Die eindeutige ID für das entsprechende history.HistoryItem.

  • isLocal

    boolean

    Chrome 115 oder höher

    „True“, wenn der Besuch von diesem Gerät stammt. Falsch, wenn es von einem anderen Gerät aus synchronisiert wurde.

  • referringVisitId

    String

    Die Besuchs-ID der Referrer-URL.

  • Übergang

    TransitionType

    Der Übergangstyp für diesen Besuch von der Verweis-URL.

  • visitId

    String

    Die eindeutige Kennung für diesen Besuch.

  • visitTime

    Nummer optional

    Zeitpunkt des Besuchs, angegeben in Millisekunden seit der Epoche.

Methoden

addUrl()

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

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

Parameters

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

deleteAll()

Versprechen 
chrome.history.deleteAll(
  callback?: function,
)

Löscht alle Elemente aus dem Verlauf.

Parameters

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

deleteRange()

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

Entfernt alle Elemente innerhalb des angegebenen Zeitraums aus dem Verlauf. Seiten werden nur dann aus dem Verlauf entfernt, wenn alle Besuche in diesen Bereich fallen.

Parameters

  • Angebot

    Objekt

    • endTime

      Zahl

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

    • startTime

      Zahl

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

deleteUrl()

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

Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.

Parameters

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getVisits()

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

Ruft Informationen zu Besuchen einer URL ab.

Parameters

Rückgaben

  • Promise<VisitItem[]>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

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

Durchsucht den Verlauf des letzten Besuchs jeder Seite, die der Abfrage entspricht.

Parameters

  • Abfrage

    Objekt

    • endTime

      Nummer optional

      Ergebnisse auf Nutzer beschränken, die vor diesem Datum besucht wurden, angegeben in Millisekunden seit der Epoche

    • maxResults

      Nummer optional

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

    • startTime

      Nummer optional

      Ergebnisse auf die Ergebnisse beschränken, die nach diesem Datum besucht wurden, angegeben in Millisekunden seit der Epoche. Wenn keine Property angegeben ist, wird die Standardeinstellung 24 Stunden verwendet.

    • Text

      String

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (results: HistoryItem[])=>void

Rückgaben

  • Promise<HistoryItem[]>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onVisited

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

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

Parameters

onVisitRemoved

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

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

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (removed: object)=>void

    • entfernt

      Objekt

      • allHistory

        boolean

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

      • urls

        string[] optional