chrome.webNavigation

Описание

Используйте 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

Chrome 44+

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

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44+

Причина навигации. Используются те же типы переходов, что и в 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 указывает на то, что это основной кадр; положительное значение указывает на идентификатор подкадра.

      • frameType
        Chrome 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.

      • frameType
        Chrome 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+

        Жизненный цикл документа.

      • frameId

        число

        0 означает, что навигация происходит в окне содержимого вкладки; положительное значение означает навигацию в подфрейме. Идентификаторы фреймов уникальны для данной вкладки и процесса.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Устарело с версии Chrome 50.

        Идентификатор процесса (processId) больше не устанавливается для этого события, поскольку процесс, который будет отображать результирующий документ, становится известен только после выполнения команды onCommit.

        Значение -1.

      • tabId

        число

        Идентификатор вкладки, в которой будет происходить навигация.

      • метка времени

        число

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

      • url

        нить

  • фильтры

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

    • Условия, которым должен удовлетворять 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Идентификатор процесса, запускающего рендерер для данного кадра.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

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

      • квалификаторы перехода

        Список квалификационных этапов перехода.

      • transitionType

        Причина навигации.

      • 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Идентификатор процесса, запускающего рендерер для данного кадра.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

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

      • url

        нить

  • фильтры

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

    • Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • sourceFrameId

        число

        Идентификатор фрейма с sourceTabId, в котором запускается навигация. 0 указывает на главный фрейм.

      • sourceProcessId

        число

        Идентификатор процесса, запускающего рендерер для исходного кадра.

      • sourceTabId

        число

        Идентификатор вкладки, в которой запускается навигация.

      • tabId

        число

        Идентификатор вкладки, в которой открыт URL-адрес.

      • метка времени

        число

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

      • 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Идентификатор процесса, запускающего рендерер для данного кадра.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

        Время, когда DOM страницы был полностью сформирован, в миллисекундах с начала эпохи.

      • 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Устарело с версии Chrome 50.

        Идентификатор процесса (processId) больше не задан для этого события.

        Значение -1.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

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

      • 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Идентификатор процесса, запускающего рендерер для данного кадра.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

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

      • квалификаторы перехода

        Список квалификационных этапов перехода.

      • transitionType

        Причина навигации.

      • 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 указывает на то, что навигация происходит в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах одной вкладки.

      • Chrome 106+

        Тип фрейма, в котором происходила навигация.

      • parentDocumentId

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

        Chrome 106+

        UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Chrome 74+

        Идентификатор родительского фрейма или -1 , если это главный фрейм.

      • processId

        число

        Идентификатор процесса, запускающего рендерер для данного кадра.

      • tabId

        число

        Идентификатор вкладки, в которой происходит навигация.

      • метка времени

        число

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

      • квалификаторы перехода

        Список квалификационных этапов перехода.

      • transitionType

        Причина навигации.

      • url

        нить

  • фильтры

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

    • Условия, которым должен удовлетворять URL-адрес, на который осуществляется переход. Поля 'schemes' и 'ports' объекта UrlFilter игнорируются для этого события.

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

Событие срабатывает, когда содержимое вкладки заменяется другой (обычно предварительно отрисованной) вкладкой.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • replacedTabId

        число

        Идентификатор вкладки, которая была заменена.

      • tabId

        число

        Идентификатор вкладки, заменившей старую вкладку.

      • метка времени

        число

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