chrome.history

Описание

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

Разрешения

history

Это разрешение вызывает предупреждение .

Манифест

Чтобы использовать API истории, вы должны объявить разрешение «история» в манифесте расширения . Например:

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

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

API истории использует тип перехода , чтобы описать, как браузер перешел к определенному URL-адресу при конкретном посещении. Например, если пользователь посещает страницу, щелкнув ссылку на другой странице, тип перехода — «ссылка».

В следующей таблице описан каждый тип перехода.

Тип перехода	Описание
"связь"	Пользователь попал на эту страницу, перейдя по ссылке на другой странице.
"напечатанный"	Пользователь получил эту страницу, введя URL-адрес в адресной строке. Также используется для других явных действий навигации. См. также сгенерированный , который используется в случаях, когда пользователь выбрал вариант, который совсем не похож на URL-адрес.
"авто_закладка"	Пользователь попал на эту страницу по предложению в пользовательском интерфейсе — например, через пункт меню.
"авто_подкадр"	Подкадровая навигация. Это любой контент, который автоматически загружается во фрейм не верхнего уровня. Например, если страница состоит из нескольких фреймов, содержащих рекламу, URL-адреса этих объявлений имеют этот тип перехода. Пользователь может даже не осознавать, что содержимое этих страниц представляет собой отдельный фрейм, и поэтому его может не волновать URL-адрес (см. также manual_subframe ).
"manual_subframe"	Для переходов по подкадрам, которые явно запрошены пользователем и генерируют новые записи навигации в списке вперед/назад. Явно запрошенный кадр, вероятно, более важен, чем автоматически загруженный кадр, поскольку пользователя, вероятно, волнует тот факт, что запрошенный кадр был загружен.
"сгенерированный"	Пользователь попал на эту страницу, набрав в адресной строке и выбрав запись, не похожую на URL. Например, совпадение может иметь URL-адрес страницы результатов поиска Google, но может отображаться для пользователя как «Поиск в Google по ...». Это не совсем то же самое, что вводная навигация, поскольку пользователь не ввел и не увидел целевой URL-адрес. См. также ключевое слово .
"auto_toplevel"	Страница была указана в командной строке или является стартовой.
"form_submit"	Пользователь заполнил значения в форме и отправил ее. Обратите внимание, что в некоторых ситуациях — например, когда форма использует сценарий для отправки содержимого — отправка формы не приводит к переходу этого типа.
"перезагрузить"	Пользователь перезагрузил страницу либо нажав кнопку перезагрузки, либо нажав Enter в адресной строке. Восстановление сеанса и повторное открытие закрытой вкладки также используют этот тип перехода.
"ключевое слово"	URL-адрес был создан на основе заменяемого ключевого слова, отличного от поставщика поиска по умолчанию. См. также ключевое слово_generated .
"ключевое слово_сгенерировано"	Соответствует посещению, созданному по ключевому слову. См. также ключевое слово .

Примеры

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

Типы

HistoryItem

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

Характеристики

• идентификатор

  нить

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

• ПоследнееВизиттиме

  номер необязательно

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

• заголовок

  строка необязательна

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

• напечатаноCount

  номер необязательно

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

• URL

  строка необязательна

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

• визитКаунт

  номер необязательно

  Сколько раз пользователь переходил на эту страницу.

TransitionType

Хром 44+

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

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

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

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

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

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

"manual_subframe"
Пользователь попал на эту страницу, выбрав что-то в подкадре.

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

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

"form_submit"
Пользователь попал на эту страницу, заполнив значения в форме и отправив ее. Не все отправки форм используют этот тип перехода.

"перезагрузить"
Пользователь перезагрузил страницу либо нажав кнопку перезагрузки, либо нажав Enter в адресной строке. Восстановление сеанса и повторное открытие закрытой вкладки также используют этот тип перехода.

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

"ключевое слово_сгенерировано"
Соответствует посещению, созданному по ключевому слову.

UrlDetails

Хром 88+

Характеристики

• URL

  нить

  URL-адрес операции. Он должен быть в формате, возвращаемом при вызове history.search() .

VisitItem

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

Характеристики

• идентификатор

  нить

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

• isLocal

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

  Хром 115+

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

• ссылающийсяVisitId

  нить

  Идентификатор посещения реферера.

• переход

  Тип перехода

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

• идентификатор посещения

  нить

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

• время посещения

  номер необязательно

  Когда произошел этот визит, указано в миллисекундах с начала эпохи.

Методы

addUrl()

Обещать

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

Добавляет URL-адрес в историю в текущий момент с типом перехода «ссылка».

Параметры

• подробности

  URL-подробности

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  ()=>void

Возврат

• Обещание<void>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

deleteAll()

Обещать

chrome.history.deleteAll(
  callback?: function,
)

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

Параметры

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  ()=>void

Возврат

• Обещание<void>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

deleteRange()

Обещать

chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

Параметры

• диапазон

  объект

  • время окончания

    число

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

  • время начала

    число

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

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  ()=>void

Возврат

• Обещание<void>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

deleteUrl()

Обещать

chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

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

Параметры

• подробности

  URL-подробности

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  ()=>void

Возврат

• Обещание<void>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getVisits()

Обещать

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

Получает информацию о посещениях URL-адреса.

Параметры

• подробности

  URL-подробности

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (results: VisitItem[])=>void

  • Результаты

    ПосетитеЭлемент []

Возврат

• Обещание< VisitItem []>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

search()

Обещать

chrome.history.search(
  query: object,
  callback?: function,
)

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

Параметры

• запрос

  объект

  • время окончания

    номер необязательно

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

  • maxResults

    номер необязательно

    Максимальное количество результатов для получения. По умолчанию 100.

  • время начала

    номер необязательно

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

  • текст

    нить

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

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (results: HistoryItem[])=>void

  • Результаты

    Элемент истории []

Возврат

• Обещание< HistoryItem []>

  Хром 96+

  Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

События

onVisited

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

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

Параметры

• перезвонить

  функция

  Параметр callback выглядит так:

  (result: HistoryItem)=>void

  • результат

    Элемент истории

onVisitRemoved

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

Вызывается, когда один или несколько URL-адресов удаляются из истории. После удаления всех посещений URL-адрес удаляется из истории.

Параметры

• перезвонить

  функция

  Параметр callback выглядит так:

  (removed: object)=>void

  • удаленный

    объект

    • всеИстория

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

      Верно, если вся история была удалена. Если это правда, то URL-адреса будут пустыми.

    • URL-адреса

      строка[] необязательно