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