topSites.get()

Получает массив, содержащий информацию о страницах, которые пользователь часто и недавно посещал.

Браузеры хранят список страниц, которые пользователь часто и недавно посещает. Они используют этот список, чтобы помочь пользователю легко возвращаться к этим местам. Например, браузер Firefox по умолчанию предоставляет список наиболее посещаемых страниц на странице "Новая вкладка".

Чтобы определить, какие страницы появляются в списке и в каком порядке, браузер сочетает «частоту» — насколько часто пользователь посещал страницу — и «недавность» — насколько недавно пользователь посещал страницу.

Браузер может затем применить дополнительное фильтрование к этому списку перед представлением его пользователю. Например, на странице "Новая вкладка" в Firefox отображается только одна страница на домен, и пользователь может заблокировать страницы, чтобы они не отображались в списке.

API topSites.get() позволяет расширению получить доступ к этому списку. Вызов без каких-либо опций предоставит отфильтрованный список страниц — то есть тот, который отображается на странице "Новая вкладка". Однако, предоставляя различные параметры, расширение может получить неотфильтрованный список страниц.

Это асинхронная функция, которая возвращает Promise.

Для использования API topSites у вас должен быть разрешение "topSites" API разрешение.

Синтаксис

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

Параметры

options

object. Параметры для изменения списка возвращаемых страниц. Они могут включать любые из следующих свойств:

includeBlocked Необязательно: Boolean. Включить страницы, которые пользователь удалил со страницы "Новая вкладка". По умолчанию false.
includeFavicon Необязательно: Boolean. Включить значки сайтов (favicons) в результатах, где они доступны. По умолчанию false.
includePinned Необязательно: Boolean. Включает сайты, которые пользователь добавил в закладки в новой вкладке Firefox. По умолчанию false.
includeSearchShortcuts Необязательно: Boolean. Включает ярлыки поиска, которые отображаются на новой вкладке Firefox. По умолчанию false.
limit Необязательно: Integer. Количество страниц для возврата. Должно быть числом от 1 до 100 включительно. По умолчанию 12.
newtab Необязательно: Boolean. Если включено, метод возвращает список страниц, отображаемых при открытии новой вкладки. Если включено и установлено в true, метод игнорирует все другие параметры, кроме limit и includeFavicon. По умолчанию false.
onePerDomain Необязательно: Boolean. Включать только по одной странице на домен. По умолчанию true.

Возвращаемое значение

A Promise. Это значение будет выполнено с массивом объектов MostVisitedURL, по одному для каждой страницы, перечисленной на странице "Новая вкладка" браузера. Если произошла ошибка, обещание будет отклонено с сообщением об ошибке.

Совместимость с браузерами

	Рабочий стол						Мобильные устройства
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari на iOS	Samsung Internet
`get`	Да	79	52 Начиная с Firefox 78, пользователь может отключить функцию браузера "Популярные сайты" переключив предпочтение "browser.newtabpage.activity-stream.feeds.system.topsites". В этом случае `topSites.get()` всегда будет возвращать список наиболее посещаемых сайтов, независимо от значения параметра `newtab`.	?	Да	Нет	?	?	52–79	?	Нет	?
`options`	Нет	Нет	63	?	Нет	Нет	?	?	63–79	?	Нет	?

Примеры

Этот код выводит заголовок и URL всех страниц на странице "Новая вкладка":

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 всех популярных страниц, включая заблокированные пользователем, и потенциально включая несколько страниц на одном домене:

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

Примеры расширений

top-sites

Примечание: Этот API основан на Chromium API chrome.topSites.

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/topSites/get