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

Manifest

Sie müssen die Berechtigung „history“ im Erweiterungsmanifest deklarieren, um die History API zu verwenden. 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 aufruft, indem er auf einer anderen Seite auf einen Link klickt, ist der Übergangstyp „link“.

In der folgenden Tabelle werden die einzelnen Übergangstypen beschrieben.

ÜbergangstypBeschreibung
„typed“Der Nutzer hat diese Seite aufgerufen, indem er die URL in die Adressleiste eingegeben hat. Wird auch für andere explizite Navigationsaktionen verwendet. Siehe auch generated für Fälle, in denen der Nutzer eine Auswahl getroffen hat, die überhaupt nicht wie eine URL aussah.
„auto_bookmark“Der Nutzer hat diese Seite über einen Vorschlag in der Benutzeroberfläche aufgerufen, z. B. über ein Menüelement.
„auto_subframe“Navigation im Subframe. Das sind alle Inhalte, die automatisch in einem Frame geladen werden, der nicht auf der obersten Ebene liegt. Wenn eine Seite beispielsweise aus mehreren Frames mit Anzeigen besteht, haben die Anzeigen-URLs diesen Übergangstyp. Der Nutzer merkt möglicherweise nicht einmal, dass der Inhalt auf diesen Seiten ein separater Frame ist, und kümmert sich daher nicht um die URL (siehe auch manual_subframe).
„manual_subframe“Für Subframe-Navigationen, die explizit vom Nutzer angefordert werden und neue Navigationseinträge in der Liste „Zurück/Vorwärts“ generieren. Ein explizit angeforderter Frame ist wahrscheinlich wichtiger als ein automatisch geladener Frame, da der Nutzer sich wahrscheinlich dafür interessiert, dass der angeforderte Frame geladen wurde.
„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. Ein Abgleich kann beispielsweise die URL einer Google-Suchergebnisseite enthalten, wird dem Nutzer aber als „Bei Google suchen nach …“ angezeigt. Diese sind nicht ganz mit eingegebenen Navigationsvorgängen vergleichbar, da der Nutzer die Ziel-URL nicht eingegeben oder gesehen 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 es gesendet. In bestimmten Situationen, z. B. wenn in einem Formular ein Skript zum Senden von Inhalten verwendet wird, führt das Senden eines Formulars nicht zu diesem Ü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 wurde aus einem ersetzbaren Keyword generiert, das nicht der Standardsuchanbieter ist. Siehe auch keyword_generated.
„keyword_generated“Entspricht einem Besuch, der für ein Keyword generiert wurde. Siehe auch Keyword.

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()

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

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

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

Löscht alle Elemente aus dem Verlauf.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): 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.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

deleteUrl()

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

Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getVisits()

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

Ruft Informationen zu Besuchen einer URL ab.

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (results: VisitItem[]) => void

Ausgabe

  • Promise<VisitItem[]>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): 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.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (results: HistoryItem[]) => void

Ausgabe

  • Promise<HistoryItem[]>

    Chrome 96 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

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