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. См. также ключевое слово.
"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 выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

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

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

deleteAll()

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

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

Параметры

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

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

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

    () => void

Возвраты

  • Promise<void>

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

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

deleteRange()

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

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

Параметры

  • диапазон

    Объект

    • endTime

      число

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

    • startTime

      число

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

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

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

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

    () => void

Возвраты

  • Promise<void>

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

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

deleteUrl()

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

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

Параметры

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

    UrlDetails

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

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

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

    () => 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[]) => void

Возвраты

  • Promise<VisitItem[]>

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

    Объекты Promise поддерживаются только в 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[]) => void

Возвраты

  • Promise<HistoryItem[]>

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

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

События

onVisited

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

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

Параметры

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

    function

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

    (result: HistoryItem) => void

onVisitRemoved

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

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

Параметры

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

    function

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

    (removed: object) => void

    • удалено

      Объект

      • allHistory

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

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

      • URL

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