Описание
Используйте API chrome.webNavigation для получения уведомлений о статусе выполняющихся запросов навигации.
Разрешения
webNavigationМанифест
Для всех методов и событий chrome.webNavigation необходимо указать разрешение "webNavigation" в манифесте расширения . Например:
{
"name": "My extension",
...
"permissions": [
"webNavigation"
],
...
}
порядок событий
При успешном завершении навигации события срабатывают в следующем порядке:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
Любая ошибка, возникающая в процессе, приводит к событию onErrorOccurred . Для конкретного перехода после onErrorOccurred никаких дальнейших событий не генерируется.
Если навигационный фрейм содержит подфреймы, то его onCommitted срабатывает до события onBeforeNavigate любого из его дочерних фреймов; в то время как onCompleted срабатывает после всех событий onCompleted его дочерних фреймов.
Если фрагмент ссылки на фрейм изменяется, срабатывает событие onReferenceFragmentUpdated . Это событие может сработать в любое время после onDOMContentLoaded , даже после onCompleted .
Если для изменения состояния фрейма используется API истории (например, с помощью history.pushState() ), генерируется событие onHistoryStateUpdated . Это событие может сработать в любое время после onDOMContentLoaded .
Если при навигации страница восстанавливается из кэша «Назад/Вперед» , событие onDOMContentLoaded не сработает. Событие не срабатывает, потому что контент уже полностью загружен к моменту первого посещения страницы.
Если навигация была инициирована через Chrome Instant или Instant Pages , в текущую вкладку заменяется полностью загруженной страницей. В этом случае срабатывает событие onTabReplaced .
Связь с событиями webRequest
Между событиями API webRequest и событиями API webNavigation нет определенной последовательности. Возможно, события webRequest будут поступать и для фреймов, в которых уже началась новая навигация, или же навигация продолжится только после полной загрузки сетевых ресурсов.
В целом, события webNavigation тесно связаны с состоянием навигации, отображаемым в пользовательском интерфейсе, тогда как события webRequest соответствуют состоянию сетевого стека, которое, как правило, непрозрачно для пользователя.
Идентификаторы вкладок
Не все вкладки, используемые для навигации, соответствуют реальным вкладкам в пользовательском интерфейсе Chrome, например, вкладке, которая находится в процессе предварительной отрисовки. Такие вкладки недоступны через API вкладок , и вы не можете запросить информацию о них через webNavigation.getFrame или webNavigation.getAllFrames . После замены такой вкладки срабатывает событие onTabReplaced , и она становится доступной через эти API.
Временные метки
Важно отметить, что некоторые технические особенности обработки операционной системой отдельных процессов Chrome могут привести к расхождению во времени между самим браузером и процессами расширений. Это означает, что свойство timeStamp событий WebNavigation гарантирует только внутреннюю согласованность. Сравнение одного события с другим даст вам правильное смещение между ними, но сравнение их с текущим временем внутри расширения (например, с помощью (new Date()).getTime() ) может дать неожиданные результаты.
Идентификаторы кадров
Фреймы внутри вкладки можно идентифицировать по идентификатору фрейма. Идентификатор основного фрейма всегда равен 0, идентификаторы дочерних фреймов — положительное число. После того, как документ создан во фрейме, его идентификатор остается неизменным на протяжении всего времени существования документа. Начиная с Chrome 49, этот идентификатор также остается неизменным на протяжении всего времени существования фрейма (при нескольких переходах по ссылкам).
Из-за многопроцессной природы Chrome, вкладка может использовать разные процессы для отображения исходной и целевой веб-страницы. Поэтому, если навигация происходит в новом процессе, вы можете получать события как от новой, так и от старой страницы до тех пор, пока новая навигация не будет подтверждена (т.е. событие onCommitted не будет отправлено для нового главного фрейма). Другими словами, может быть несколько ожидающих последовательностей событий webNavigation с одним и тем же frameId . Последовательности можно различать по ключу processId .
Также обратите внимание, что во время предварительной загрузки процесс может переключаться несколько раз. Это происходит, когда загрузка перенаправляется на другой сайт. В этом случае вы будете получать повторяющиеся события onBeforeNavigate и onErrorOccurred , пока не получите последнее событие onCommitted .
Ещё одна проблема, связанная с расширениями, — это жизненный цикл фрейма. Фрейм содержит документ (который связан с зафиксированным URL-адресом). Документ может изменяться (например, при переходе по ссылкам), но frameId остаётся неизменным, поэтому сложно связать изменения в конкретном документе только с frameId . Мы вводим концепцию documentId , уникального идентификатора для каждого документа. Если при переходе по фрейму открывается новый документ, идентификатор изменится. Это поле полезно для определения момента изменения состояния жизненного цикла страниц (между предварительной отрисовкой/активностью/кэшированием), поскольку оно остаётся неизменным.
Типы и квалификаторы переходов
Событие onCommitted в API webNavigation имеет свойства transitionType и transitionQualifiers . Тип перехода совпадает с типом перехода, используемым в API history, описывающим способ перехода браузера к данному URL-адресу. Кроме того, могут быть возвращены несколько квалификаторов перехода , которые дополнительно определяют навигацию.
Существуют следующие квалификаторы перехода:
| квалификационный переход | Описание |
|---|---|
| "client_redirect" | В процессе навигации произошло одно или несколько перенаправлений, вызванных JavaScript или метатегами обновления страницы. |
| "server_redirect" | В процессе навигации произошло одно или несколько перенаправлений, вызванных HTTP-заголовками, отправленными с сервера. |
| "forward_back" | Для начала навигации пользователь использовал кнопки «Вперед» или «Назад». |
| "from_address_bar" | Пользователь инициировал навигацию из адресной строки (также известной как Omnibox). |
Примеры
Чтобы опробовать этот API, установите пример webNavigation API из репозитория chrome-extension-samples .
Типы
TransitionQualifier
Перечисление
"client_redirect" "server_redirect" "forward_back" "from_address_bar"
TransitionType
Причина навигации. Используются те же типы переходов, что и в API истории. Это те же типы переходов, что и в API истории, за исключением того, что вместо "auto_toplevel" используется "start_page" (для обратной совместимости).
Перечисление
"связь" "напечатано" "auto_bookmark" "auto_subframe" "manual_subframe" "сгенерированный" "start_page" "form_submit" "перезагрузка" "ключевое слово" "keyword_generated"
Методы
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
): Promise<object[] | undefined>
Получает информацию обо всех фреймах заданной вкладки.
Параметры
- подробности
объект
Информация о вкладке, с которой можно получить все кадры.
- tabId
число
Идентификатор вкладки.
- перезвонить
функция необязательна
Параметр
callbackвыглядит следующим образом:(details?: object[]) => void
- подробности
объект[] необязательный
Список фреймов на указанной вкладке; значение равно null, если указанный идентификатор вкладки недействителен.
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- произошла ошибка
логический
Значение true, если последняя навигация в этом фрейме была прервана ошибкой, то есть сработало событие onErrorOccurred.
- frameId
число
Идентификатор кадра. 0 указывает на то, что это основной кадр; положительное значение указывает на идентификатор подкадра.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- url
нить
URL-адрес, связанный в данный момент с этим фреймом.
Возвраты
Promise<object[] | undefined>
Chrome 93+Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
): Promise<object | undefined>
Получает информацию о заданном фрейме. Фрейм — это элемент <iframe> или <frame> веб-страницы, идентифицируемый идентификатором вкладки и идентификатором фрейма.
Параметры
- подробности
объект
Информация о кадре, для которого необходимо получить информацию.
- documentId
строка необязательный
Chrome 106+UUID документа. Если указаны frameId и/или tabId, они будут проверены на соответствие документу, найденному по указанному идентификатору документа.
- frameId
число необязательно
Идентификатор фрейма на указанной вкладке.
- processId
число необязательно
Устарело с версии Chrome 49.Теперь каждый кадр однозначно идентифицируется по идентификатору вкладки и идентификатору кадра; идентификатор процесса больше не требуется и, следовательно, игнорируется.
Идентификатор процесса, запускающего средство отрисовки для этой вкладки.
- tabId
число необязательно
Идентификатор вкладки, в которой находится фрейм.
- перезвонить
функция необязательна
Параметр
callbackвыглядит следующим образом:(details?: object) => void
- подробности
объект необязательный
Информация о запрошенном кадре, пустое значение, если указанный идентификатор кадра и/или идентификатор вкладки недействительны.
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- произошла ошибка
логический
Значение true, если последняя навигация в этом фрейме была прервана ошибкой, то есть сработало событие onErrorOccurred.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Идентификатор родительского фрейма или
-1, если это главный фрейм. - url
нить
URL-адрес, связанный с данным фреймом, если фрейм, идентифицированный по frameId, существовал в какой-то момент на данной вкладке. Тот факт, что URL-адрес связан с данным frameId, не означает, что соответствующий фрейм все еще существует.
Возвраты
Promise<object | undefined>
Chrome 93+Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.
События
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда вот-вот начнётся навигация.
Параметры
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
объект
- Chrome 106+
Жизненный цикл документа.
число
0 означает, что навигация происходит в окне содержимого вкладки; положительное значение означает навигацию в подфрейме. Идентификаторы фреймов уникальны для данной вкладки и процесса.
- Chrome 106+
Тип фрейма, в котором происходила навигация.
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
число
Идентификатор родительского фрейма или
-1, если это главный фрейм.число
Устарело с версии Chrome 50.Идентификатор процесса (processId) больше не устанавливается для этого события, поскольку процесс, который будет отображать результирующий документ, становится известен только после выполнения команды onCommit.
Значение -1.
число
Идентификатор вкладки, в которой будет происходить навигация.
число
Время, когда браузер собирался начать навигацию, в миллисекундах с начала эпохи.
нить
объект необязательный
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Событие срабатывает при подтверждении перехода по ссылке. Документ (и ресурсы, на которые он ссылается, такие как изображения и подфреймы) могут еще загружаться, но по крайней мере часть документа уже получена с сервера, и браузер принял решение переключиться на новый документ.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда была зафиксирована навигация, в миллисекундах с начала эпохи.
- квалификаторы перехода
Список квалификационных этапов перехода.
- transitionType
Причина навигации.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Событие срабатывает, когда документ, включая ресурсы, на которые он ссылается, полностью загружен и инициализирован.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время завершения загрузки документа в миллисекундах с начала эпохи.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Событие срабатывает при создании нового окна или новой вкладки в существующем окне для размещения навигации.
Параметры
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
объект
число
Идентификатор фрейма с sourceTabId, в котором запускается навигация. 0 указывает на главный фрейм.
число
Идентификатор процесса, запускающего рендерер для исходного кадра.
число
Идентификатор вкладки, в которой запускается навигация.
число
Идентификатор вкладки, в которой открыт URL-адрес.
число
Время, когда браузер собирался создать новое представление, в миллисекундах с начала эпохи.
нить
URL-адрес, который откроется в новом окне.
объект необязательный
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Событие срабатывает, когда DOM страницы полностью сформирован, но указанные ресурсы могут не загрузиться до конца.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда DOM страницы был полностью сформирован, в миллисекундах с начала эпохи.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Этот сигнал срабатывает при возникновении ошибки и прерывании навигации. Это может произойти, например, из-за ошибки в сети или по вине пользователя.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- ошибка
нить
Описание ошибки.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Устарело с версии Chrome 50.Идентификатор процесса (processId) больше не задан для этого события.
Значение -1.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда произошла ошибка, в миллисекундах с начала эпохи.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Событие срабатывает при обновлении истории фрейма до нового URL-адреса. Все будущие события для этого фрейма будут использовать обновленный URL-адрес.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда была зафиксирована навигация, в миллисекундах с начала эпохи.
- квалификаторы перехода
Список квалификационных этапов перехода.
- transitionType
Причина навигации.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Событие срабатывает при обновлении фрагмента ссылки на кадр. Все будущие события для этого кадра будут использовать обновленный URL.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- documentId
нить
Chrome 106+UUID загруженного документа.
- жизненный цикл документаChrome 106+
Жизненный цикл документа.
- frameId
число
Значение 0 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.
- frameTypeChrome 106+
Тип фрейма, в котором происходила навигация.
- parentDocumentId
строка необязательный
Chrome 106+UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
- parentFrameId
число
Chrome 74+Идентификатор родительского фрейма или
-1, если это главный фрейм. - processId
число
Идентификатор процесса, запускающего рендерер для данного кадра.
- tabId
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда была зафиксирована навигация, в миллисекундах с начала эпохи.
- квалификаторы перехода
Список квалификационных этапов перехода.
- transitionType
Причина навигации.
- url
нить
- фильтры
объект необязательный
- url
Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Событие срабатывает, когда содержимое вкладки заменяется другой (обычно предварительно отрисованной) вкладкой.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(details: object) => void
- подробности
объект
- replacedTabId
число
Идентификатор вкладки, которая была заменена.
- tabId
число
Идентификатор вкладки, заменившей старую вкладку.
- метка времени
число
Время, когда произошла замена, в миллисекундах с начала эпохи.