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 гарантирует только внутреннюю согласованность. Сравнение одного события с другим даст вам timeStamp смещение между ними, но сравнение их с текущим временем внутри расширения (например, с помощью (new Date()).getTime() ) может привести к неожиданным результатам.

Идентификаторы кадров

Фреймы внутри вкладки можно идентифицировать по идентификатору фрейма. Идентификатор основного фрейма всегда равен 0, идентификатор дочерних фреймов — положительное число. После того, как документ создан во фрейме, его идентификатор фрейма остаётся неизменным на протяжении всего времени существования документа. Начиная с Chrome 49, этот идентификатор также остаётся неизменным на протяжении всего времени существования фрейма (при нескольких переходах).

Из-за многопроцессной природы Chrome вкладка может использовать разные процессы для отображения исходного и конечного веб-страниц. Таким образом, если навигация происходит в новом процессе, вы можете получать события как с новой, так и со старой страницы до тех пор, пока новая навигация не будет зафиксирована (т.е. не будет отправлено событие onCommitted для нового основного фрейма). Другими словами, может быть несколько ожидающих последовательностей событий webNavigation с одинаковым frameId . Последовательности можно различать по ключу processId .

Также обратите внимание, что во время предварительной загрузки процесс может переключаться несколько раз. Это происходит при перенаправлении загрузки на другой сайт. В этом случае вы будете получать повторяющиеся события onBeforeNavigate и onErrorOccurred , пока не получите финальное событие onCommitted .

Ещё одна концепция, вызывающая проблемы с расширениями, — это жизненный цикл фрейма. Фрейм содержит документ (связанный с закреплённым URL-адресом). Документ может измениться (например, при навигации), но frameId останется неизменным, поэтому сложно связать какие-либо события в конкретном документе только с frameIds . Мы вводим концепцию documentId , который является уникальным идентификатором для каждого документа. При переходе по фрейму и открытии нового документа идентификатор изменится. Это поле полезно для определения того, когда страницы меняют своё состояние жизненного цикла (между pre-render, active и cached), поскольку оно остаётся неизменным.

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

Событие webNavigation onCommitted имеет свойства transitionType и transitionQualifiers . Тип перехода совпадает с используемым в API истории, описывающим, как браузер перешёл к данному URL-адресу. Кроме того, могут быть возвращены несколько квалификаторов перехода , которые более подробно определяют навигацию.

Существуют следующие квалификаторы перехода:

Переходный квалификатор Описание
"client_redirect" Во время навигации произошло одно или несколько перенаправлений, вызванных JavaScript или метатегами Refresh на странице.
"server_redirect" Во время навигации произошло одно или несколько перенаправлений, вызванных заголовками HTTP, отправленными с сервера.
"вперед_назад" Для начала навигации пользователь использовал кнопку «Вперед» или «Назад».
"from_address_bar" Пользователь инициировал навигацию из адресной строки (также известной как омнибокс).

Примеры

Чтобы опробовать этот API, установите пример API webNavigation из репозитория chrome-extension-samples .

Типы

TransitionQualifier

Хром 44+

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

"client_redirect"

"server_redirect"

"вперед_назад"

"from_address_bar"

TransitionType

Хром 44+

Причина навигации. Используются те же типы переходов, что определены в API истории. Это те же типы переходов, что определены в API истории, за исключением того, что вместо "auto_toplevel" используется « "start_page" » (для обратной совместимости).

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

"связь"

"напечатанный"

"авто_закладка"

"auto_subframe"

"manual_subframe"

"сгенерированный"

"стартовая_страница"

"form_submit"

"перезагрузка"

"ключевое слово"

"keyword_generated"

Методы

getAllFrames()

chrome.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

Извлекает информацию обо всех кадрах заданной вкладки.

Параметры

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

    объект

    Информация о вкладке, из которой следует извлечь все кадры.

    • tabId

      число

      Идентификатор вкладки.

Возврат

  • Обещание<объект[] | неопределено>

    Хром 93+

getFrame()

chrome.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

Получает информацию о заданном фрейме. Фрейм относится к элементу <iframe> или <frame> веб-страницы и идентифицируется идентификатором вкладки и идентификатором фрейма.

Параметры

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

    объект

    Информация о кадре, о котором требуется получить информацию.

    • documentId

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

      Хром 106+

      UUID документа. Если указаны frameId и/или tabId, они будут проверены на соответствие документу, найденному по указанному идентификатору.

    • frameId

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

      Идентификатор фрейма в данной вкладке.

    • processId

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

      Не рекомендуется с Chrome 49

      Теперь фреймы однозначно идентифицируются по идентификатору вкладки и идентификатору фрейма; идентификатор процесса больше не нужен и поэтому игнорируется.

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

    • tabId

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

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

Возврат

  • Обещание<объект | неопределенный>

    Хром 93+

События

onBeforeNavigate

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

Срабатывает перед началом навигации.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

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

      • processId

        число

        Не рекомендуется с Chrome 50

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

        Значение -1.

      • tabId

        число

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

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

        число

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCommitted

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

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

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

      • tabId

        число

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

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

        число

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

      • transitionQualifiers

        TransitionQualifier []

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

      • тип перехода

        Тип перехода

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCompleted

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

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

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

      • tabId

        число

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

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

        число

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCreatedNavigationTarget

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

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • sourceFrameId

        число

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

      • sourceProcessId

        число

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

      • sourceTabId

        число

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

      • tabId

        число

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

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

        число

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

      • URL-адрес

        нить

        URL-адрес, который будет открыт в новом окне.

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onDOMContentLoaded

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

Срабатывает, когда DOM страницы полностью построен, но указанные ресурсы могут не завершить загрузку.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

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

      • tabId

        число

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

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

        число

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onErrorOccurred

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

Срабатывает при возникновении ошибки и прерывании навигации. Это может произойти, если произошла ошибка сети или пользователь прервал навигацию.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • ошибка

        нить

        Описание ошибки.

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

        Не рекомендуется с Chrome 50

        ProcessId больше не установлен для этого события.

        Значение -1.

      • tabId

        число

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

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

        число

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onHistoryStateUpdated

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

Срабатывает при обновлении истории фрейма с новым URL-адресом. Все будущие события для этого фрейма будут использовать обновлённый URL-адрес.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

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

      • tabId

        число

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

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

        число

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

      • transitionQualifiers

        TransitionQualifier []

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

      • тип перехода

        Тип перехода

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onReferenceFragmentUpdated

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

Срабатывает при обновлении фрагмента ссылки фрейма. Все будущие события для этого фрейма будут использовать обновлённый URL.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • documentId

        нить

        Хром 106+

        UUID загруженного документа.

      • жизненный цикл документа

        extensionTypes.DocumentLifecycle

        Хром 106+

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

      • frameId

        число

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

      • Хром 106+

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

      • parentDocumentId

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

        Хром 106+

        UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.

      • parentFrameId

        число

        Хром 74+

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

      • processId

        число

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

      • tabId

        число

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

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

        число

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

      • transitionQualifiers

        TransitionQualifier []

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

      • тип перехода

        Тип перехода

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

      • URL-адрес

        нить

  • фильтры

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

    • URL-адрес

      events.UrlFilter []

      Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onTabReplaced

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

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • replacementTabId

        число

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

      • tabId

        число

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

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

        число

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