chrome.history

refresh date: 2026-09-25 robots: noindex

Описание

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

Разрешения

history

Манифест

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

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

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

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

В таблице ниже описаны все типы переходов.

Тип переходаОписание
"typed"Пользователь перешел на эту страницу, введя URL в адресной строке. Также используется для других явных действий по навигации. Также обратите внимание на значение generated, которое используется, когда пользователь выбирает вариант, совсем не похожий на URL.
"auto_bookmark"Пользователь перешел на эту страницу по подсказке в интерфейсе, например через пункт меню.
"auto_subframe"Навигация по вложенным фреймам. Это любой контент, который автоматически загружается во фрейм, не являющийся фреймом верхнего уровня. Например, если страница состоит из нескольких фреймов с объявлениями, URL этих объявлений имеют такой тип перехода. Пользователь может даже не осознавать, что контент на этих страницах находится в отдельном фрейме, и поэтому может не обращать внимания на URL (см. также manual_subframe).
"manual_subframe"Для переходов по ссылкам в субфреймах, которые явно запрашиваются пользователем и создают новые записи в списке переходов назад и вперед. Явно запрошенный фрейм, вероятно, важнее автоматически загруженного, поскольку пользователь, скорее всего, заинтересован в том, чтобы запрошенный фрейм был загружен.
"generated"Пользователь перешел на эту страницу, введя в адресной строке запрос и выбрав вариант, который не похож на URL. Например, в качестве совпадения может быть указан URL страницы результатов поиска Google, но пользователю будет показано "Поиск в Google по запросу…". Это не совсем то же самое, что ввод URL, поскольку пользователь не вводил и не видел целевой URL. См. также ключевое слово.
"auto_toplevel"Страница указана в командной строке или является начальной.
"form_submit"Пользователь заполнил и отправил форму. Обратите внимание, что в некоторых случаях, например когда для отправки формы используется скрипт, этот тип перехода не применяется.
"reload"Пользователь перезагрузил страницу, нажав кнопку перезагрузки или клавишу Ввод в адресной строке. Этот тип перехода также используется при восстановлении сеанса и повторном открытии закрытой вкладки.
"ключевое слово"URL был создан на основе заменяемого ключевого слова, отличного от поисковой системы по умолчанию. См. также keyword_generated.
"keyword_generated"Соответствует посещению, связанному с ключевым словом. См. также ключевое слово.

Примеры

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

Типы

HistoryItem

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

Свойства

  • id

    string

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

  • lastVisitTime

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

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

  • название

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

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

  • typedCount

    number необязательный

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

  • url

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

    URL, на который перешел пользователь.

  • visitCount

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

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

TransitionType

Chrome 44 и более поздних версий;

Тип перехода на сайт с реферера.

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

"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 и более поздних версий;

Свойства

  • url

    string

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

VisitItem

Объект, содержащий информацию об одном посещении URL.

Свойства

  • id

    string

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

  • isLocal

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

    Chrome 115 и более поздние версии

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

  • referringVisitId

    string

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

  • переход

    TransitionType

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

  • visitId

    string

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

  • visitTime

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

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

Методы

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Параметры

  • подробные сведения

    UrlDetails

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

    function необязательно

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

    () =& gt;void

Возвраты

  • Promise<void>

    Chrome 96 и более поздних версий.

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

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

Удаляет все объекты из истории.

Параметры

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

    function необязательно

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

    () =& gt;void

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии

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

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

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

Параметры

  • диапазон

    Объект

    • endTime

      число

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

    • startTime

      число

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

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

    function необязательно

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

    () =& gt;void

Возвраты

  • Promise<void>

    Chrome 96 и более поздние версии

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

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Параметры

  • подробные сведения

    UrlDetails

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

    function необязательно

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

    () =& gt;void

Возвраты

  • Promise<void>

    Chrome 96 и более поздних версий.

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

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

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

Параметры

  • подробные сведения

    UrlDetails

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

    function необязательно

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

    (results: VisitItem[]) =& gt;void

Возвраты

  • Promise<VisitItem[]>

    Chrome 96 и более поздних версий.

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

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

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

Параметры

  • запрос

    Объект

    • endTime

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

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

    • maxResults

      number необязательный

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

    • startTime

      number необязательный

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

    • Текст

      string

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

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

    function необязательно

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

    (results: HistoryItem[]) =& gt;void

Возвраты

  • Promise<HistoryItem[]>

    Chrome 96 и более поздних версий.

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

События

onVisited

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

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

Параметры

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

    function

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

    (result: HistoryItem) =& gt;void

onVisitRemoved

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

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

Параметры

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

    function

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

    (removed: object) =& gt;void

    • удалено

      Объект

      • allHistory

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

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

      • URL

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