Описание
Используйте 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
.
Если навигация восстановила страницу из кэша Back Forward , событие 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-адресом). Документ может измениться (скажем, при навигации), но идентификатор фрейма — нет, поэтому трудно связать, что что-то произошло в конкретном документе, с помощью только идентификаторов фреймов . Мы представляем концепцию documentId , которая является уникальным идентификатором документа. Если переход по фрейму открывает новый документ, идентификатор изменится. Это поле полезно для определения того, когда страницы меняют состояние своего жизненного цикла (между предварительной визуализацией/активностью/кэшированием), поскольку оно остается прежним.
Типы перехода и квалификаторы
Событие onCommitted
API webNavigation имеет transitionType
transitionQualifiers
. Тип перехода тот же, что и в API истории , описывающем, как браузер перешел к этому конкретному URL-адресу. Кроме того, можно вернуть несколько квалификаторов перехода , которые дополнительно определяют навигацию.
Существуют следующие квалификаторы перехода:
Квалификатор перехода | Описание |
---|---|
"client_redirect" | Во время навигации произошло одно или несколько перенаправлений, вызванных JavaScript или метатегами обновления на странице. |
"server_redirect" | Во время навигации произошло одно или несколько перенаправлений, вызванных HTTP-заголовками, отправленными с сервера. |
"вперед_назад" | Пользователь использовал кнопку «Вперед» или «Назад», чтобы начать навигацию. |
"from_address_bar" | Пользователь инициировал навигацию из адресной строки (она же омнибокс). |
Примеры
Чтобы попробовать этот API, установите пример API webNavigation из репозитория chrome-extension-samples .
Типы
TransitionQualifier
Перечисление
"client_redirect" "server_redirect" "вперед_назад" "from_address_bar"
TransitionType
Причина навигации. Используются те же типы переходов, которые определены в API истории. Это те же типы переходов, которые определены в API истории, за исключением "start_page"
вместо "auto_toplevel"
(для обратной совместимости).
Перечисление
"связь" "напечатанный" "авто_закладка" "авто_подкадр" "manual_subframe" "сгенерированный" "начальная_страница" "form_submit" "перезагрузить" "ключевое слово" "ключевое слово_сгенерировано"
Методы
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
Получает информацию обо всех кадрах данной вкладки.
Параметры
- подробности
объект
Информация о вкладке, из которой нужно получить все кадры.
- идентификатор табуляции
число
Идентификатор вкладки.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(details?: object[]) => void
- подробности
объект[] необязательно
Список кадров на данной вкладке, имеет значение null, если указанный идентификатор вкладки недействителен.
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- произошла ошибка
логическое значение
Истинно, если последняя навигация в этом кадре была прервана из-за ошибки, т. е. было вызвано событие onErrorOccurred.
- идентификатор кадра
число
Идентификатор кадра. 0 указывает, что это основной кадр; положительное значение указывает идентификатор подкадра.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- URL
нить
URL-адрес, связанный в данный момент с этим фреймом.
Возврат
Обещание<объект[] | не определено>
Хром 93+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
Получает информацию о данном кадре. Фрейм относится к <iframe> или <frame> веб-страницы и идентифицируется идентификатором вкладки и идентификатором фрейма.
Параметры
- подробности
объект
Информация о кадре, о котором требуется получить информацию.
- идентификатор документа
строка необязательна
Хром 106+UUID документа. Если указаны FrameId и/или TabId, они будут проверены на соответствие документу, найденному по предоставленному идентификатору документа.
- идентификатор кадра
номер необязательно
Идентификатор кадра на данной вкладке.
- идентификатор процесса
номер необязательно
Устарело с Chrome 49.Кадры теперь однозначно идентифицируются по идентификатору вкладки и идентификатору кадра; идентификатор процесса больше не нужен и поэтому игнорируется.
Идентификатор процесса, запускающего средство визуализации для этой вкладки.
- идентификатор табуляции
номер необязательно
Идентификатор вкладки, в которой находится фрейм.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(details?: object) => void
- подробности
объект необязательный
Информация о запрошенном кадре, равна нулю, если указанный идентификатор кадра и/или идентификатор вкладки недействителен.
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- произошла ошибка
логическое значение
Истинно, если последняя навигация в этом кадре была прервана из-за ошибки, т. е. было вызвано событие onErrorOccurred.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Идентификатор родительского кадра или
-1
, если это основной кадр. - URL
нить
URL-адрес, связанный в данный момент с этим фреймом, если фрейм, определенный идентификатором фрейма, существовал в какой-то момент на данной вкладке. Тот факт, что URL-адрес связан с данным идентификатором фрейма, не означает, что соответствующий фрейм все еще существует.
Возврат
Обещание<объект | не определено>
Хром 93+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
События
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Вызывается, когда должна произойти навигация.
Параметры
функция
Параметр
callback
выглядит так:(details: object) => void
объект
- Хром 106+
Жизненный цикл, в котором находится документ.
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны для данной вкладки и процесса.
- Хром 106+
Тип фрейма, в котором происходила навигация.
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
число
Идентификатор родительского кадра или
-1
, если это основной кадр.число
Устарело с Chrome 50.ProcessId больше не задается для этого события, поскольку процесс, который будет отображать результирующий документ, неизвестен до onCommit.
Значение -1.
число
Идентификатор вкладки, в которой будет происходить навигация.
число
Время, когда браузер собирался начать навигацию, в миллисекундах с начала эпохи.
нить
объект необязательный
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Вызывается при фиксации навигации. Документ (и ресурсы, на которые он ссылается, например изображения и подкадры), возможно, все еще загружается, но по крайней мере часть документа была получена с сервера, и браузер решил переключиться на новый документ.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время совершения навигации в миллисекундах с начала эпохи.
- переходКвалификаторы
Список квалификаторов перехода.
- тип перехода
Причина навигации.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Запускается, когда документ, включая ресурсы, на которые он ссылается, полностью загружен и инициализирован.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время окончания загрузки документа в миллисекундах с момента.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Вызывается, когда создается новое окно или новая вкладка в существующем окне для размещения навигации.
Параметры
функция
Параметр
callback
выглядит так:(details: object) => void
объект
число
Идентификатор кадра с sourceTabId, в котором срабатывает навигация. 0 указывает на основной кадр.
число
Идентификатор процесса, который запускает средство визуализации для исходного кадра.
число
Идентификатор вкладки, в которой срабатывает навигация.
число
Идентификатор вкладки, в которой открывается URL-адрес
число
Время, когда браузер собирался создать новое представление, в миллисекундах с момента начала.
нить
URL-адрес, который будет открыт в новом окне.
объект необязательный
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Запускается, когда DOM страницы полностью создан, но ресурсы, на которые ссылаются, могут не завершить загрузку.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время, когда DOM страницы было полностью построено, в миллисекундах с начала эпохи.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Запускается, когда возникает ошибка и навигация прерывается. Это может произойти, если произошла сетевая ошибка или пользователь прервал навигацию.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- ошибка
нить
Описание ошибки.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Устарело с Chrome 50.ProcessId больше не установлен для этого события.
Значение -1.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время возникновения ошибки в миллисекундах с начала эпохи.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Вызывается, когда история фрейма обновляется до нового URL-адреса. Все будущие события для этого кадра будут использовать обновленный URL-адрес.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- Тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время совершения навигации в миллисекундах с начала эпохи.
- переходКвалификаторы
Список квалификаторов перехода.
- тип перехода
Причина навигации.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Вызывается при обновлении ссылочного фрагмента кадра. Все будущие события для этого кадра будут использовать обновленный URL-адрес.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- идентификатор документа
нить
Хром 106+UUID загруженного документа.
- Жизненный цикл документаХром 106+
Жизненный цикл, в котором находится документ.
- идентификатор кадра
число
0 указывает, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подкадре. Идентификаторы кадров уникальны в пределах вкладки.
- тип рамкиХром 106+
Тип фрейма, в котором происходила навигация.
- родительскийDocumentId
строка необязательна
Хром 106+UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
- родительскийFrameId
число
Хром 74+Идентификатор родительского кадра или
-1
, если это основной кадр. - идентификатор процесса
число
Идентификатор процесса, запускающего средство визуализации для этого кадра.
- идентификатор табуляции
число
Идентификатор вкладки, в которой происходит навигация.
- метка времени
число
Время совершения навигации в миллисекундах с начала эпохи.
- переходКвалификаторы
Список квалификаторов перехода.
- тип перехода
Причина навигации.
- URL
нить
- фильтры
объект необязательный
- URL
Условия, которым должен удовлетворять URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Вызывается, когда содержимое вкладки заменяется другой вкладкой (обычно предварительно обработанной).
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(details: object) => void
- подробности
объект
- замененTabId
число
Идентификатор замененной вкладки.
- идентификатор табуляции
число
Идентификатор вкладки, которая заменила старую вкладку.
- метка времени
число
Время, когда произошла замена, в миллисекундах с начала эпохи.