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.
Übergangstyp | Beschreibung |
---|---|
"Link" | Der Nutzer wurde durch Klicken auf einen Link auf einer anderen Seite auf diese Seite gelangt. |
"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.
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
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
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()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
Fügt dem Verlauf zum aktuellen Zeitpunkt eine URL mit dem Übergangstyp „link“ hinzu.
Parameters
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Chrome 96 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
deleteAll()
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öherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
deleteRange()
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öherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
Entfernt alle Vorkommen der angegebenen URL aus dem Verlauf.
Parameters
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Chrome 96 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Ruft Informationen zu Besuchen einer URL ab.
Parameters
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(results: VisitItem[]) => void
-
Ergebnisse
-
Rückgaben
-
Promise<VisitItem[]>
Chrome 96 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
search()
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
-
Ergebnisse
-
Rückgaben
-
Promise<HistoryItem[]>
Chrome 96 oder höherPromise-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
-
callback
Funktion
Der Parameter
callback
sieht so aus:(result: HistoryItem) => void
-
Ergebnis
-
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
-
-