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

Manifest

Sie müssen die Berechtigung „history“ im Erweiterungsmanifest deklarieren, um die History API nutzen zu können. Beispiel:

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

Übergangstypen

Die History API verwendet einen Übergangstyp, 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“.

In der folgenden Tabelle werden die einzelnen Übergangstypen beschrieben.

ÜbergangstypBeschreibung
"tippt"Der Nutzer gelangt auf diese Seite, indem er die URL in die Adressleiste eingibt. Wird auch für andere explizite Navigationsaktionen verwendet. Siehe auch Generiert. Dieser Typ wird verwendet, wenn der Nutzer eine Auswahl getroffen hat, die nicht wie eine URL aussieht.
"auto_bookmark"Der Nutzer ist über einen Vorschlag in der Benutzeroberfläche auf diese Seite gelangt, z. B. über einen Menüpunkt.
"auto_subframe"Subframe-Navigation Das sind alle Inhalte, die automatisch in einem Frame geladen werden, der nicht auf der obersten Ebene liegt. Besteht eine Seite beispielsweise aus mehreren Frames mit Anzeigen, weisen die Anzeigen-URLs diesen Übergangstyp auf. Der Nutzer erkennt möglicherweise nicht einmal, dass es sich bei dem Inhalt dieser Seiten um einen separaten Frame handelt, und ist daher für die URL möglicherweise nicht relevant (siehe auch manual_subframe).
„manueller_Subframe“Für Subframe-Navigationen, die explizit vom Nutzer angefordert werden und neue Navigationseinträge in der Zurück-/Vorwärts-Liste generieren. Ein explizit angeforderter Frame ist wahrscheinlich wichtiger als ein automatisch geladener Frame, da der Nutzer wahrscheinlich daran interessiert ist, dass der angeforderte Frame geladen wurde.
„Generiert“Der Nutzer gelangt auf diese Seite, indem er in die Adressleiste tippte und einen Eintrag auswählte, der nicht wie eine URL aussieht. Eine Übereinstimmung kann beispielsweise die URL einer Google-Suchergebnisseite enthalten, aber dem Nutzer wird möglicherweise „Mit Google suchen nach ...“ angezeigt. Dies entspricht nicht ganz der Navigation per Eingabe, da der Nutzer die Ziel-URL nicht eingegeben oder die Ziel-URL nicht angezeigt hat. Siehe auch Keyword.
"auto_toplevel"Die Seite wurde in der Befehlszeile angegeben oder ist die Startseite.
„form_submit“Der Nutzer hat Werte in ein Formular eingegeben und gesendet. Beachten Sie, dass in einigen Situationen, z. B. wenn ein Formular zum Übermitteln von Inhalten ein Skript verwendet, nicht zu diesem Übergangstyp kommt, wenn Sie ein Formular senden.
„Neu laden“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 wurde aus einem anderen austauschbaren Suchbegriff als dem Standardsuchanbieter generiert. Siehe auch keyword_generated
"keyword_generated"Entspricht einem Besuch, der für ein Keyword generiert wurde. Siehe auch Keyword.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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 nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

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