Описание
Используйте 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-адрес, по которому перешел пользователь.
- визитКаунт
номер необязательно
Сколько раз пользователь переходил на эту страницу.
Перечисление
"связь"
Пользователь попал на эту страницу, щелкнув ссылку на другой странице.
"напечатанный"
Пользователь попал на эту страницу, введя URL-адрес в адресной строке. Это также используется для других явных действий навигации.
"авто_закладка"
Пользователь попал на эту страницу по подсказке в пользовательском интерфейсе, например, через пункт меню.
"авто_подкадр"
Пользователь попал на эту страницу через подкадровую навигацию, которую он не запрашивал, например, через загрузку объявления во фрейме на предыдущей странице. Они не всегда создают новые элементы навигации в меню «Назад» и «Вперед».
"manual_subframe"
Пользователь попал на эту страницу, выбрав что-то в подкадре.
"сгенерированный"
Пользователь перешел на эту страницу, введя адресную строку и выбрав запись, которая не похожа на URL-адрес, например предложение поиска Google. Например, совпадение может иметь URL-адрес страницы результатов поиска Google, но для пользователя оно может отображаться как «Поиск в Google по ...». Они отличаются от типизированной навигации, поскольку пользователь не вводил и не видел целевой URL-адрес. Они также связаны с навигацией по ключевым словам.
"auto_toplevel"
Страница была указана в командной строке или является стартовой.
"form_submit"
Пользователь попал на эту страницу, заполнив значения в форме и отправив ее. Не все отправки форм используют этот тип перехода.
"перезагрузить"
Пользователь перезагрузил страницу либо нажав кнопку перезагрузки, либо нажав Enter в адресной строке. Восстановление сеанса и повторное открытие закрытой вкладки также используют этот тип перехода.
"ключевое слово"
URL-адрес этой страницы был создан на основе заменяемого ключевого слова, отличного от поставщика поиска по умолчанию.
"ключевое слово_сгенерировано"
Соответствует посещению, созданному по ключевому слову.
UrlDetails
Характеристики
- URL
нить
URL-адрес операции. Он должен быть в формате, возвращаемом при вызове
history.search()
.
VisitItem
Объект, инкапсулирующий одно посещение URL-адреса.
Характеристики
- идентификатор
нить
Уникальный идентификатор соответствующей
history.HistoryItem
. - isLocal
логическое значение
Хром 115+True, если посещение было совершено на этом устройстве. False, если оно было синхронизировано с другого устройства.
- ссылающийсяVisitId
нить
Идентификатор посещения реферера.
- переход
Тип перехода для этого посещения от источника перехода.
- идентификатор посещения
нить
Уникальный идентификатор этого посещения.
- время посещения
номер необязательно
Когда произошел этот визит, указано в миллисекундах с начала эпохи.
Методы
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
Добавляет 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-адреса из истории.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Хром 96+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
Получает информацию о посещениях 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-адреса
строка[] необязательно