chrome.history

Beschreibung

Sie können die chrome.history API verwenden, um mit dem Datensatz des Browsers zu den besuchten Seiten zu interagieren. Sie können URLs im Browserverlauf hinzufügen, entfernen und abfragen. Wie Sie die Verlaufsseite durch Ihre eigene Version überschreiben, erfahren Sie unter Seiten überschreiben.

Berechtigungen

history

Manifest

Sie müssen den „Verlauf“ deklarieren im Erweiterungsmanifest, 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 zu einer bestimmten URL navigiert ist. für einen bestimmten Besuch. Wenn ein Nutzer beispielsweise eine Seite besucht, indem er auf einen Link auf einer anderen Seite klickt, wird der Übergangstyp ist „Link“.

In der folgenden Tabelle werden die einzelnen Übergangstypen beschrieben.

ÜbergangstypBeschreibung
"typed"Der Nutzer hat diese Seite durch Eingabe der URL in die Adressleiste aufgerufen. Wird auch für andere explizite Navigationsaktionen verwendet. Siehe auch Generiert. Diese Option wird in Fällen verwendet, in denen 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. Dies sind alle Inhalte, die automatisch in einem Frame geladen werden, der sich nicht auf der obersten Ebene befindet. Besteht eine Seite beispielsweise aus mehreren Frames, die Anzeigen enthalten, weisen diese Anzeigen-URLs diesen Übergangstyp auf. Möglicherweise erkennt der Nutzer nicht einmal, dass der Inhalt dieser Seiten ein separater Frame ist, und interessiert sich daher nicht unbedingt für die URL (siehe auch manual_subframe).
„manual_subframe“Für Subframe-Navigationen, die explizit vom Nutzer angefordert werden und neue Navigationseinträge in der Back-Forward-Liste generieren. Ein explizit angeforderter Frame ist wahrscheinlich wichtiger als ein automatisch geladener Frame, da dem Nutzer wahrscheinlich die Tatsache wichtig ist, dass der angeforderte Frame geladen wurde.
"Generiert"Der Nutzer wurde auf diese Seite weitergeleitet, indem er etwas in die Adressleiste eingegeben und einen Eintrag ausgewählt hat, der nicht wie eine URL aussieht. Eine Übereinstimmung kann beispielsweise die URL einer Google-Suchergebnisseite enthalten, für den Nutzer jedoch „Mit Google suchen nach ...“. Diese Navigationen unterscheiden sich von eingegebenen Navigationen, 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 einigen Situationen, z. B. wenn ein Formular Inhalte über ein Skript übermittelt, führt das Senden eines Formulars nicht zu diesem Übergangstyp.
„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. Dieser Übergangstyp wird auch für die Sitzungswiederherstellung und das Öffnen eines geschlossenen Tabs verwendet.
"Keyword"Die URL wurde aus einem anderen austauschbaren Suchbegriff als dem Standardsuchanbieter generiert. Siehe auch keyword_generated
„keyword_generated“ (Keyword-generiert)Entspricht einem Besuch, der für ein Keyword generiert wurde. Siehe auch Keyword.

Beispiele

Um diese API auszuprobieren, installieren Sie das Verlaufs-API-Beispiel aus chrome-extension-samples. zu erstellen.

Typen

HistoryItem

Ein Objekt, das ein Ergebnis einer Verlaufsabfrage einschließt.

Attribute

  • id

    String

    Die eindeutige Kennzeichnung für den Artikel.

  • lastVisitTime

    Zahl optional

    Zeitpunkt, zu dem diese Seite zuletzt geladen wurde, angegeben in Millisekunden seit der Epoche.

  • Titel

    String optional

    Der Titel der Seite beim letzten Laden.

  • typedCount

    Zahl optional

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

  • URL

    String optional

    Die URL, die ein Nutzer aufgerufen hat.

  • visitCount

    Zahl optional

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

TransitionType

Chrome (ab Version 44)

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

Enum

"link"
Der Nutzer ist durch Klicken auf einen Link auf einer anderen Seite auf diese Seite gelangt.

"typed"
Der Nutzer ist durch Eingabe der URL in die Adressleiste zu dieser Seite gelangt. 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, beispielsweise über einen Menüpunkt.

"auto_subframe"
Der Nutzer ist über die Subframe-Navigation, die er nicht angefordert hat, auf diese Seite gelangt, zum Beispiel durch das Laden einer Anzeige in einem Frame auf der vorherigen Seite. Dadurch werden nicht immer neue Navigationseinträge im Zurück- und Vorwärtsmenü generiert.

"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 aussieht, z. B. ein Vorschlag der Google Suche. Eine Übereinstimmung kann beispielsweise die URL einer Google-Suchergebnisseite enthalten, für den Nutzer jedoch „Mit Google suchen nach ...“. Diese unterscheiden sich von typisierten Navigationen, da der Nutzer die Ziel-URL nicht eingegeben oder gesehen hat. Sie stehen auch in Zusammenhang mit der Navigation durch Keywords.

"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 ausfüllt und das Formular absendet. Dieser Übergangstyp 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. Dieser Übergangstyp wird auch für die Sitzungswiederherstellung und den geschlossenen Tab „Erneut öffnen“ verwendet.

"keyword"
Die URL für diese Seite wurde von einem anderen austauschbaren Suchbegriff als dem Standardsuchanbieter generiert.

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

UrlDetails

Chrome (ab Version 88)

Attribute

  • URL

    String

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

VisitItem

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

Attribute

  • id

    String

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

  • isLocal

    boolean

    Chrome 115 oder höher

    „True“, wenn der Besuch von diesem Gerät stammt. „False“, wenn es von einem anderen Gerät 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

    Zahl optional

    Zeitpunkt des Besuchs, angegeben in Millisekunden seit der Epoche.

Methoden

addUrl()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

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

deleteAll()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.deleteAll(
  callback?: function,
)

Löscht alle Elemente aus dem Verlauf.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

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

deleteRange()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

Parameter

  • Angebot

    Objekt

    • endTime

      Zahl

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

    • startTime

      Zahl

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

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

deleteUrl()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

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

getVisits()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Ruft Informationen zu Besuchen einer URL ab.

Parameter

  • Details

    UrlDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (results: VisitItem[]) => void

Gibt Folgendes zurück:

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 und höher

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

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.history.search(
  query: object,
  callback?: function,
)

Durchsucht den Verlauf nach dem Zeitpunkt des letzten Besuchs jeder Seite, die der Anfrage entspricht.

Parameter

  • Abfrage

    Objekt

    • endTime

      Zahl optional

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

    • maxResults

      Zahl optional

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

    • startTime

      Zahl optional

      Beschränkt die Ergebnisse auf diejenigen, die nach diesem Datum besucht wurden, angegeben in Millisekunden seit der Epoche. Wenn die Eigenschaft nicht angegeben ist, wird der Standardwert von 24 Stunden verwendet.

    • Text

      String

      Eine Freitext-Abfrage an den Verlaufsdienst. Lassen Sie dieses Feld leer, um alle Seiten abzurufen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (results: HistoryItem[]) => void

Gibt Folgendes zurück:

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 und höher

    Promise-Objekte 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, wobei die HistoryItem-Daten für diese URL bereitgestellt werden. Dieses Ereignis wird ausgelöst, bevor die Seite geladen wurde.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result: HistoryItem) => void

onVisitRemoved

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

Wird ausgelöst, wenn mindestens eine URL aus dem Verlauf entfernt wird Wurden alle Besuche entfernt, wird die URL dauerhaft aus dem Verlauf gelöscht.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (removed: object) => void

    • entfernt

      Objekt

      • allHistory

        boolean

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

      • URLs

        string[] optional