browser.history

Описание

Используйте chrome.history API для взаимодействия с записью браузера о посещенных страницах. Вы можете добавлять и удалять URL в истории браузера, а также запрашивать их. Чтобы заменить страницу истории собственной версией, ознакомьтесь с разделом Переопределение страниц.

Разрешения

history

Для взаимодействия с историей браузера пользователя используйте History API.

Чтобы использовать History API, объявите разрешение "history" в манифесте расширения. Пример:

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

Основные понятия и использование

Типы переходов

History API использует типы переходов, чтобы описать, как браузер перешел на определенный URL во время определенного посещения. Например, если пользователь переходит на страницу по ссылке, тип перехода – "ссылка". Список типов переходов приведен в справочной документации.

Примеры

Чтобы попробовать этот API, установите пример History API из хранилища chrome-extension-samples.

Типы

HistoryItem

Объект, инкапсулирующий один результат запроса истории.

Свойства

  • id

    string

    Уникальный идентификатор объекта.

  • lastVisitTime

    number (необязательно)

    Время последней загрузки страницы в миллисекундах с начала эпохи.

  • название

    Строка (необязательно)

    Заголовок страницы при последней загрузке.

  • typedCount

    number (необязательно)

    Количество переходов на эту страницу путем ввода адреса.

  • url

    Строка (необязательно)

    URL, по которому перешел пользователь.

  • visitCount

    number (необязательно)

    Количество переходов пользователя на эту страницу.

TransitionType

Chrome 44+ browser.* начиная с Chrome 148

Тип перехода для этого посещения с его реферера.

Перечисление

"link"
Пользователь перешел на эту страницу по ссылке на другой странице.

"typed"
Пользователь перешел на страницу, введя URL в адресной строке. Это также используется для других явных действий навигации.

"auto_bookmark"
Пользователь перешел на страницу по подсказке в интерфейсе, например через пункт меню.

"auto_subframe"
Пользователь перешел на эту страницу через навигацию по субфрейму, которую он не запрашивал, например через загрузку объявления во фрейме на предыдущей странице. При этом в меню навигации назад и вперед не всегда появляются новые записи.

"manual_subframe"
Пользователь перешел на страницу, выбрав элемент в субфрейме.

"generated"
Пользователь перешел на страницу, введя в адресной строке запрос, не похожий на URL, например выбрав подсказку при поиске Google Поиска. Например, совпадение может содержать URL страницы результатов поиска Google, но пользователь увидит текст "Искать в Google…". Это не то же самое, что переход по введенному URL, поскольку пользователь не вводил и не видел целевой URL. Они также связаны с навигацией по ключевым словам.

"auto_toplevel"
Страница была указана в командной строке или является стартовой.

form_submit
Пользователь перешел на страницу, заполнив и отправив форму. Этот тип перехода используется не для всех отправленных форм.

"reload"
Пользователь перезагрузил страницу, нажав кнопку перезагрузки или клавишу Ввод в адресной строке. Этот тип перехода также используется при восстановлении сеанса и повторном открытии закрытой вкладки.

"keyword"
URL этой страницы был создан на основе заменяемого ключевого слова, которое не относится к поисковой системе по умолчанию.

"keyword_generated"
Посещение, связанное с ключевым словом.

UrlDetails

Chrome 88+ browser.* начиная с Chrome 148

Свойства

  • url

    string

    URL операции. Формат должен соответствовать возвращаемому при вызове history.search().

VisitItem

Объект, инкапсулирующий одно посещение URL.

Свойства

  • id

    string

    Уникальный идентификатор соответствующего объекта history.HistoryItem.

  • isLocal

    Логическое значение

    Chrome 115 и более поздние версии browser.* начиная с Chrome 148

    True, если посещение было совершено с этого устройства. False, если оно было синхронизировано с другого устройства.

  • referringVisitId

    string

    Идентификатор посещения, связанный с URL перехода.

  • переход

    TransitionType

    Тип перехода для этого посещения с его реферера.

  • visitId

    string

    Уникальный идентификатор посещения.

  • visitTime

    number (необязательно)

    Время посещения в миллисекундах с начала эпохи.

Методы

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

Добавляет URL в историю в текущее время с типом перехода "ссылка".

Параметры

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148

deleteAll()

browser.history.deleteAll(): Promise<void>

Удаляет все элементы из истории.

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

Удаляет из истории все элементы за указанный период. Страницы будут удалены из истории, только если все посещения попадают в указанный диапазон.

Параметры

  • диапазон

    Объект

    • endTime

      число

      Элементы, добавленные в историю до этой даты, представленные в миллисекундах с начала эпохи.

    • startTime

      число

      Элементы, добавленные в историю после этой даты, в миллисекундах с начала эпохи.

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

Удаляет из истории все вхождения указанного URL.

Параметры

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

Извлекает информацию о посещениях URL.

Параметры

Возвраты

  • Promise<VisitItem[]>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

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

Параметры

  • запрос

    Объект

    • endTime

      number (необязательно)

      Ограничить результаты теми, которые были посещены до этой даты, представленной в миллисекундах с начала эпохи.

    • maxResults

      number (необязательно)

      Максимальное количество результатов, которые нужно получить. Значение по умолчанию – 100.

    • startTime

      number (необязательно)

      Ограничить результаты теми, которые были посещены после этой даты, представленной в миллисекундах с начала эпохи. Если свойство не указано, по умолчанию будет установлено значение 24 часа.

    • Текст

      string

      Запрос в свободной форме к сервису истории. Если оставить это поле пустым, будут получены все страницы.

Возвраты

  • Promise<HistoryItem[]>

    Chrome 96 и более поздние версии browser.* начиная с Chrome 148

События

onVisited

browser.history.onVisited.addListener(
  callback: function,
)

Срабатывает при посещении URL и предоставляет данные HistoryItem для этого URL. Это событие активируется до загрузки страницы.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: HistoryItem) => void

onVisitRemoved

browser.history.onVisitRemoved.addListener(
  callback: function,
)

Срабатывает, когда один или несколько URL удаляются из истории. Когда все посещения удалены, URL удаляется из истории.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (removed: object) => void

    • удалено

      Объект

      • allHistory

        Логическое значение

        True, если вся история была удалена. Если задано значение true, URL будут пустыми.

      • URL

        string[] необязательно