topSites.get()

获取包含用户最近经常访问的页面信息的数组。

浏览器会保留用最近经常访问的页面的列表。它们使用此列表来帮助用户轻松返回这些地方。例如，Firefox 默认提供了在“新标签”页中显示的最常访问页面的列表。

要确定哪些页面出现在列表中，以及它们出现的顺序，浏览器会结合“频率”（用户访问页面的频率）和“最近性”（用户最近访问页面的时间）。

然后，浏览器可能会在将此列表呈现给用户之前对其进行进一步过滤。例如，在 Firefox 中，“新标签”页仅列出每个域名中的一个页面，用户也可以阻止某些页面出现在列表中。

topSites.get() API 允许扩展访问此列表。如果不使用任何选项地调用，它将提供过滤后的页面列表——即出现在“新标签”页中的列表。但是，扩展也可以通过提供各种选项获取未经过滤的页面列表。

这是一个返回 Promise 的异步函数。

要使用 topSites API，你必须预先取得“topSites”API 权限。

语法

let gettingTopSites = browser.topSites.get(
    options  // 对象
)

参数

options

object。用于修改返回页面列表的选项。可以包含如下属性：

includeBlocked 可选: Boolean。包含用户已从“新标签”页面中移除的页面。默认为 false。
includeFavicon 可选: Boolean。在结果中包含 favicon（对于有可用 favicon 的页面）。默认为 false。
includePinned 可选: Boolean。包含用户已固定到 Firefox 新标签页的站点。默认为 false。
includeSearchShortcuts 可选: Boolean。包含在 Firefox 新标签页上显示的搜索快捷方式。默认为 false。
limit 可选: Integer。要返回的页面数。这必须是介于 1 和 100 之间的数字（包括 1 和 100）。默认为 12。
newtab 可选: Boolean。如果包含，该方法将返回用户打开新标签页时返回的页面列表。如果包含并设置为 true，该方法将忽略除 limit 和 includeFavicon 之外的所有其他参数。默认为 false。
onePerDomain 可选: Boolean。仅为每个域名包含一个页面。默认为 true。

返回值

Promise。这将被兑现为包含若干个 MostVisitedURL 对象的数组，且各对象代表浏览器的“新标签”页中列出的一个页面。如果发生错误，promise 将以错误消息拒绝。

浏览器兼容性

BCD tables only load in the browser

示例

下面的代码记录“新标签”页中所有页面的标题和 URL：

function logTopSites(topSitesArray) {
  for (const topSite of topSitesArray) {
    console.log(`标题：${topSite.title}，URL：${topSite.url}`);
  }
}

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

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

下面的代码则记录所有最常访问页面的标题和 URL，包括用户已阻止的页面，可能包括同一域名的多个页面：

function logTopSites(topSitesArray) {
  for (const topSite of topSitesArray) {
    console.log(`标题：${topSite.title}，URL：${topSite.url}`);
  }
}

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

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

示例扩展

top-sites