topSites.get()

Ruft ein Array ab, das Informationen über Seiten enthält, die der Benutzer häufig und kürzlich besucht hat.

Browser führen eine Liste von Seiten, die der Benutzer oft und kürzlich besucht. Sie verwenden diese Liste, um dem Benutzer zu helfen, leicht zu diesen Orten zurückzukehren. Firefox beispielsweise bietet standardmäßig eine Liste der meistbesuchten Seiten auf der "Neuer Tab"-Seite.

Um zu bestimmen, welche Seiten in der Liste erscheinen und in welcher Reihenfolge sie erscheinen, kombiniert der Browser "Häufigkeit" – wie oft der Benutzer die Seite besucht hat – und "Aktualität" – wie kürzlich der Benutzer die Seite besucht hat.

Der Browser kann diese Liste dann weiter filtern, bevor er sie dem Benutzer präsentiert. Zum Beispiel listet die "Neuer Tab"-Seite in Firefox nur eine Seite pro Domain auf, und der Benutzer kann Seiten blockieren, um sie aus der Liste zu entfernen.

Die topSites.get() API ermöglicht es einer Erweiterung, Zugang zu dieser Liste zu erhalten. Ohne Optionen aufgerufen, liefert sie die gefilterte Liste der Seiten – also die, die auf der "Neuer Tab"-Seite erscheint. Durch das Angeben verschiedener Optionen ist es jedoch möglich, dass eine Erweiterung die ungefilterte Liste der Seiten erhält.

Dies ist eine asynchrone Funktion, die ein Promise zurückgibt.

Um die topSites API zu verwenden, müssen Sie die "topSites" API-Berechtigung haben.

Syntax

js
let gettingTopSites = browser.topSites.get(
    options  // object
)

Parameter

options

object. Optionen zur Modifikation der zurückgegebenen Seitenliste. Diese können folgende Eigenschaften umfassen:

includeBlocked Optional

Boolean. Einschließen von Seiten, die der Benutzer von der "Neuer Tab"-Seite entfernt hat. Standardwert ist false.

includeFavicon Optional

Boolean. Favicons in den Ergebnissen enthalten, für Seiten, wo sie verfügbar sind. Standardwert ist false.

includePinned Optional

Boolean. Enthält Seiten, die der Benutzer an die Firefox-Neutabseite angepinnt hat. Standardwert ist false.

includeSearchShortcuts Optional

Boolean. Beinhaltet Suchverknüpfungen, die auf der Firefox-Neutabseite erscheinen. Standardwert ist false.

limit Optional

Integer. Die Anzahl der zurückzugebenden Seiten. Dies muss eine Zahl zwischen 1 und 100 sein, einschließlich. Standardwert ist 12.

newtab Optional

Boolean. Wenn enthalten, gibt die Methode die Liste der Seiten zurück, die angezeigt werden, wenn der Benutzer einen neuen Tab öffnet. Wenn enthalten und auf true gesetzt, ignoriert die Methode alle anderen Parameter außer limit und includeFavicon. Standardwert ist false.

onePerDomain Optional

Boolean. Nur eine Seite pro Domain einbeziehen. Standardwert ist true.

Rückgabewert

Ein Promise. Dieses wird mit einem Array von MostVisitedURL-Objekten erfüllt, eines für jede Seite, die auf der "Neuer Tab"-Seite des Browsers aufgelistet ist. Tritt ein Fehler auf, wird das Versprechen mit einer Fehlermeldung zurückgewiesen.

Browser-Kompatibilität

BCD tables only load in the browser

Beispiele

Dieser Code protokolliert den Titel und die URL aller Seiten auf der "Neuer Tab"-Seite:

js
function logTopSites(topSitesArray) {
  for (const topSite of topSitesArray) {
    console.log(`Title: ${topSite.title}, URL: ${topSite.url}`);
  }
}

function onError(error) {
  console.error(error);
}

browser.topSites.get().then(logTopSites, onError);

Dieser Code protokolliert den Titel und die URL aller Top-Seiten, einschließlich derjenigen, die der Benutzer blockiert hat, und potenziell einschließlich mehrerer Seiten in derselben Domain:

js
function logTopSites(topSitesArray) {
  for (const topSite of topSitesArray) {
    console.log(`Title: ${topSite.title}, URL: ${topSite.url}`);
  }
}

function onError(error) {
  console.error(error);
}

browser.topSites
  .get({
    includeBlocked: true,
    onePerDomain: false,
  })
  .then(logTopSites, onError);

Beispiel-Erweiterungen

Hinweis: Diese API basiert auf der chrome.topSites API von Chromium.