chrome.history

Описание

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

Разрешения

history

Манифест

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

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

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

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

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

Тип перехода Описание
"напечатанный" Пользователь перешёл на эту страницу, введя URL в адресную строку. Также используется для других явных навигационных действий. См. также сгенерированный , который используется в случаях, когда пользователь выбрал вариант, совершенно не похожий на URL.
"авто_закладка" Пользователь перешел на эту страницу через подсказку в пользовательском интерфейсе — например, через пункт меню.
"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-адрес, по которому перешел пользователь.

  • visitCount

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

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

TransitionType

Хром 44+

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

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

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

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

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

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

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

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

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

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

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

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

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

UrlDetails

Хром 88+

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

  • URL-адрес

    нить

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

VisitItem

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

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

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

    нить

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

  • isLocal

    булев

    Хром 115+

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

  • referingVisitId

    нить

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

  • переход

    Тип перехода

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

  • visitId

    нить

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

  • visitTime

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

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

Методы

addUrl()

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

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

Параметры

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

    UrlDetails

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

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

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

    () => void

Возврат

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

    Хром 96+

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

deleteAll()

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

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

Параметры

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

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

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

    () => void

Возврат

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

    Хром 96+

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

deleteRange()

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

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

Параметры

  • диапазон

    объект

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

      число

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

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

      число

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

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

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

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

    () => void

Возврат

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

    Хром 96+

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

deleteUrl()

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

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

Параметры

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

    UrlDetails

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

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

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

    () => void

Возврат

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

    Хром 96+

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

getVisits()

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

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

Параметры

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

    UrlDetails

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

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

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

    (results: VisitItem[]) => void

Возврат

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

    Хром 96+

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

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

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

Параметры

  • запрос

    объект

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

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

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

    • 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

    • удаленный

      объект

      • всяИстория

        булев

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

      • URL-адреса

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