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 .

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

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

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

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

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

Еще одна проблематичная концепция расширений — это жизненный цикл фрейма. Во фрейме размещается документ (который связан с зафиксированным URL-адресом). Документ может измениться (скажем, при навигации), но идентификатор кадра — нет, поэтому трудно связать, что что-то произошло в конкретном документе, с помощью только идентификаторов кадра . Мы представляем концепцию documentId , которая является уникальным идентификатором документа. Если переход по фрейму открывает новый документ, идентификатор изменится. Это поле полезно для определения того, когда страницы меняют состояние своего жизненного цикла (между предварительной визуализацией/активностью/кэшированием), поскольку оно остается прежним.

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

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

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

Квалификатор перехода Описание
"client_redirect" Во время навигации произошло одно или несколько перенаправлений, вызванных JavaScript или метатегами обновления на странице.
"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 истории, за исключением "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+

    Промисы поддерживаются в Манифесте 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+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onBeforeNavigate

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

Вызывается, когда должна произойти навигация.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • Жизненный цикл документа
        Хром 106+

        Жизненный цикл, в котором находится документ.

      • идентификатор кадра

        число

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

      • Хром 106+

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

      • родительскийDocumentId

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

        Хром 106+

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

      • родительскийFrameId

        число

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

      • идентификатор процесса

        число

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

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

        Значение -1.

      • идентификатор табуляции

        число

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

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

        число

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

      • URL

        нить

  • фильтры

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

    • Условия, которым должен удовлетворять 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.

onCreatedNavigationTarget

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

Вызывается, когда создается новое окно или новая вкладка в существующем окне для размещения навигации.

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • исходныйFrameId

        число

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

      • исходныйпроцессид

        число

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

      • исходный табид

        число

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

      • идентификатор табуляции

        число

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

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

        число

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

      • 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» 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-адрес, по которому осуществляется переход. Поля «схемы» и «порты» UrlFilter игнорируются для этого события.

onTabReplaced

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

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

Параметры

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

    функция

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

    (details: object) => void

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

      объект

      • замененTabId

        число

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

      • идентификатор табуляции

        число

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

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

        число

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