topSites.get()

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

浏览器会保存一个用户经常和最近访问的页面列表。他们使用此列表来帮助用户轻松返回这些位置。例如，Firefox 默认情况下会在“新标签页”中提供一个最近访问的页面列表。

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

然后，浏览器可能会在此列表上应用进一步的过滤，然后再将其呈现给用户。例如，在 Firefox 中，“新标签页”只会列出每个域的一个页面，并且用户可以阻止页面出现在列表中。

topSites.get() API 使扩展能够访问此列表。在不提供任何选项的情况下调用它，将提供已过滤的页面列表，即“新标签页”中显示的列表。但是，通过提供各种选项，扩展可以获取未过滤的页面列表。

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

要使用 topSites API，您必须拥有“topSites”API 权限。

语法

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

参数

options

object. 用于修改返回的页面列表的选项。这可能包含以下任何属性

includeBlocked 可选

Boolean. 包含用户已从“新标签页”中删除的页面。默认为 false。

includeFavicon 可选

Boolean. 在结果中包含网站图标，对于有网站图标的页面。默认为 false。

includePinned 可选

Boolean. 包含用户已固定到 Firefox 新标签页的网站。默认为 false。

includeSearchShortcuts 可选

Boolean. 包含显示在 Firefox 新标签页上的搜索快捷方式。默认为 false。

limit 可选

Integer. 要返回的页面数。这必须是一个介于 1 和 100（含）之间的数字。默认为 12。

newtab 可选

Boolean. 如果包含，则该方法返回用户打开新标签页时返回的页面列表。如果包含，并且设置为 true，则该方法将忽略所有其他参数，除了 limit 和 includeFavicon。默认为 false。

onePerDomain 可选

Boolean. 每个域只包含一个页面。默认为 true。

返回值

一个Promise。这将使用一个MostVisitedURL对象的数组来完成，每个对象代表浏览器“新标签页”中列出的每个页面。如果发生错误，则 promise 将被拒绝并显示错误消息。

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

示例

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

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);

此代码记录所有顶级页面的标题和 URL，包括用户已阻止的页面，并且可能包含同一域中的多个页面

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);

扩展示例

注意：此 API 基于 Chromium 的chrome.topSites API。