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 останется неизменным, поэтому сложно связать какие-либо события в конкретном документе только с frameIds . Мы вводим концепцию documentId , который является уникальным идентификатором для каждого документа. При переходе по фрейму и открытии нового документа идентификатор изменится. Это поле полезно для определения того, когда страницы меняют своё состояние жизненного цикла (между pre-render, active и cached), поскольку оно остаётся неизменным.

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

Событие onCommitted API webNavigation имеет свойства 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,
  callback?: function,
): Promise<object[] | undefined>

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

Параметры

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

    объект

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

    • tabId

      число

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

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

    функция необязательна

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

    (details?: object[]) => void

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

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

      Список фреймов в указанной вкладке, null, если указанный идентификатор вкладки недействителен.

      • documentId

        нить

        Хром 106+

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

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

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

        Хром 106+

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

      • Произошла ошибка

        булев

        True, если последняя навигация в этом кадре была прервана ошибкой, т.е. сработало событие onErrorOccurred.

      • frameId

        число

        Идентификатор кадра. 0 указывает, что это основной кадр; положительное значение указывает идентификатор подкадра.

      • frameType

        Тип рамы

        Хром 106+

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

      • parentDocumentId

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

        Хром 106+

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

      • parentFrameId

        число

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

      • processId

        число

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

      • URL-адрес

        нить

        URL-адрес, в данный момент связанный с этим фреймом.

Возврат

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

    Хром 93+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getFrame()

Обещать
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
): Promise<object | undefined>

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

Параметры

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

    объект

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

    • documentId

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

      Хром 106+

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

    • frameId

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

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

    • processId

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

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

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

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

    • tabId

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

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

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

    функция необязательна

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

    (details?: object) => void

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

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

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

      • documentId

        нить

        Хром 106+

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

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

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

        Хром 106+

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

      • Произошла ошибка

        булев

        True, если последняя навигация в этом кадре была прервана ошибкой, т.е. сработало событие onErrorOccurred.

      • frameType

        Тип рамы

        Хром 106+

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

      • parentDocumentId

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

        Хром 106+

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

      • parentFrameId

        число

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

      • URL-адрес

        нить

        URL-адрес, связанный с этим фреймом в данный момент, если фрейм, идентифицированный frameId, существовал когда-либо на данной вкладке. Тот факт, что URL-адрес связан с указанным frameId, не означает, что соответствующий фрейм всё ещё существует.

Возврат

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

    Хром 93+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

События

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

        число

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

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

        число

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