topSites.get()

Erhält ein Array mit Informationen über Seiten, die der Benutzer häufig und kürzlich besucht hat.

Browser führen eine Liste von Seiten, die der Benutzer häufig und kürzlich besucht. Diese Liste wird verwendet, um dem Benutzer zu helfen, leicht zu diesen Stellen zurückzukehren. Zum Beispiel bietet Firefox standardmäßig eine Liste der am häufigsten besuchten 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 vor der Präsentation an den Benutzer weiter filtern. Beispielsweise listet die "Neuer Tab"-Seite in Firefox nur eine Seite pro Domain auf, und der Benutzer kann Seiten blockieren, damit sie nicht in der Liste erscheinen.

Die topSites.get() API ermöglicht einer Erweiterung den Zugriff auf diese Liste. Wenn sie ohne Optionen aufgerufen wird, liefert sie die gefilterte Liste der Seiten – also diejenige, die auf der "Neuer Tab"-Seite erscheint. Durch die Angabe von verschiedenen Optionen kann eine Erweiterung jedoch auch die ungefilterte Liste der Seiten abrufen.

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 jede der folgenden 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. Einschließen von Favicons in den Ergebnissen, für Seiten, auf denen sie verfügbar sind. Standardwert ist false.

includePinned Optional

Boolean. Einschließt Seiten, die der Benutzer an die Firefox-"Neuer Tab"-Seite angeheftet hat. Standardwert ist false.

includeSearchShortcuts Optional

Boolean. Einschließt Suchverknüpfungen, die auf der Firefox-"Neuer Tab"-Seite 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 eingeschlossen, gibt die Methode die Liste der Seiten zurück, die angezeigt werden, wenn der Benutzer einen neuen Tab öffnet. Wenn eingeschlossen und auf true gesetzt, ignoriert die Methode alle anderen Parameter außer limit und includeFavicon. Standardwert ist false.

onePerDomain Optional

Boolean. Enthält nur eine Seite pro Domain. Standardwert ist true.

Rückgabewert

Ein Promise. Dieses wird mit einem Array von MostVisitedURL-Objekten erfüllt, eines für jede Seite, die in der "Neuer Tab"-Seite des Browsers gelistet ist. Wenn ein Fehler auftritt, wird das Promise mit einer Fehlermeldung abgelehnt.

Browser-Kompatibilität

Beispiele

Dieser Code protokolliert den Titel und die URL für alle 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 für alle Top-Seiten, einschließlich der vom Benutzer blockierten und potenziell mehreren Seiten 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);

Beispielerweiterungen

Hinweis: Diese API basiert auf Chromiums chrome.topSites API.