chrome.history

дата обновления: 2026-09-25 robots: noindex

Описание

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

Разрешения

history

Манифест

Для использования API истории необходимо указать разрешение «история» в манифесте расширения . Например:

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

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

The history API uses a transition type to describe how the browser navigated to a particular URL on a particular visit. For example, if a user visits a page by clicking a link on another page, the transition type is "link".

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

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

Примеры

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

Типы

HistoryItem

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

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

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

    нить

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

  • lastVisitTime

    число необязательно

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

  • заголовок

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

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

  • typedCount

    число необязательно

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

  • url

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

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

  • количество посещений

    число необязательно

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

TransitionType

Chrome 44+

Тип перехода для данного визита, полученный от источника перехода.

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

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

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

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

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

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

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

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

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

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

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

"keyword_generated"
Соответствует посещению, совершенному по ключевому слову.

UrlDetails

Chrome 88+

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

  • url

    нить

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

VisitItem

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

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

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

    нить

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

  • isLocal

    логический

    Chrome 115+

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

  • referVisitId

    нить

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

  • переход

    TransitionType

    Тип перехода для данного визита, полученный от источника перехода.

  • visitId

    нить

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

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

    число необязательно

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

Методы

addUrl()

Обещать
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Параметры

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

    UrlDetails

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

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

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

deleteAll()

Обещать
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

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

Параметры

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

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

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

deleteRange()

Обещать
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

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

Параметры

  • диапазон

    объект

    • endTime

      число

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

    • startTime

      число

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

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

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

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

deleteUrl()

Обещать
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

Параметры

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

    UrlDetails

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

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

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

getVisits()

Обещать
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

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

Параметры

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

    UrlDetails

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

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

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

    (results: VisitItem[]) => void

Возвраты

  • Promise< VisitItem []>

    Chrome 96+

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

Обещать
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

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

Параметры

  • запрос

    объект

    • endTime

      число необязательно

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

    • maxResults

      число необязательно

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

    • startTime

      число необязательно

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

    • текст

      нить

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

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

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

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

    (results: HistoryItem[]) => void

Возвраты

  • Promise< HistoryItem []>

    Chrome 96+

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

События

onVisited

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

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

Параметры

onVisitRemoved

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

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

Параметры

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

    функция

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

    (removed: object) => void

    • удаленный

      объект

      • всяИстория

        логический

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

      • URL-адреса

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