browser.webNavigation

Описание

Используйте chrome.webNavigation API, чтобы получать уведомления о статусе запросов навигации во время поездки.

Разрешения

webNavigation

Для всех методов и событий browser.webNavigation необходимо объявить разрешение "webNavigation" в манифесте расширения. Пример:

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

Основные понятия и использование

Порядок событий

Если переход выполнен успешно, события запускаются в следующем порядке:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

Любая ошибка, возникающая в процессе, приводит к событию onErrorOccurred. После onErrorOccurred события не регистрируются.

Если фрейм, в котором выполняется навигация, содержит дочерние фреймы, то его событие onCommitted активируется до того, как активируются события onBeforeNavigate дочерних фреймов, а событие onCompleted – после того, как активируются события onCompleted дочерних фреймов.

Если фрагмент ссылки фрейма изменен, активируется событие onReferenceFragmentUpdated. Это событие может активироваться в любой момент после onDOMContentLoaded, даже после onCompleted.

Если для изменения состояния фрейма используется History API (например, history.pushState()), активируется событие onHistoryStateUpdated. Это событие может быть активировано в любое время после onDOMContentLoaded.

Если при переходе страница была восстановлена из возвратного кеша, событие onDOMContentLoaded не активируется. Событие не активируется, поскольку контент уже загружен при первом посещении страницы.

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

Связь с событиями webRequest

Порядок событий webRequest API и webNavigation API не определен. События webRequest могут по-прежнему поступать для фреймов, которые уже начали новую навигацию, или навигация может продолжаться только после полной загрузки сетевых ресурсов.

В целом события webNavigation тесно связаны с состоянием навигации, которое отображается в интерфейсе, а события webRequest соответствуют состоянию сетевого стека, которое обычно скрыто от пользователя.

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

Не все вкладки, на которых выполняется навигация, соответствуют реальным вкладкам в интерфейсе Chrome. Например, это может быть вкладка, на которой выполняется предварительная отрисовка. Такие вкладки недоступны через Tabs 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. Документ может измениться (например, при навигации), но frameId останется прежним, поэтому сложно связать событие в определенном документе только с frameId. Мы вводим понятие documentId – уникального идентификатора документа. Если фрейм перенаправляет пользователя и открывает новый документ, идентификатор изменится. Это поле полезно для определения того, когда страницы меняют свое состояние жизненного цикла (между предварительной отрисовкой, активным состоянием и кешированием), поскольку оно остается неизменным.

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

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

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

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

Примеры

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

Типы

TransitionQualifier

Chrome 44+ browser.* начиная с Chrome 148

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

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44+ browser.* начиная с Chrome 148

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

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

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Методы

getAllFrames()

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

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

Параметры

• подробные сведения

  Объект

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

  • tabId

    число

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

Возвраты

• Promise<object[] | undefined>

  Chrome 93 и более поздних версий browser.* начиная с Chrome 148

getFrame()

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

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

Параметры

• подробные сведения

  Объект

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

  • documentId

    Строка (необязательно)

    Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

  • frameId

    number (необязательно)

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

  • processId

    number (необязательно)

    Не поддерживается начиная с Chrome 49

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

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

  • tabId

    number (необязательно)

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

Возвраты

• Promise<object | undefined>

  Chrome 93 и более поздних версий browser.* начиная с Chrome 148

События

onBeforeNavigate

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

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

    • processId

      число

      Устарело начиная с Chrome 50

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

      Значение -1.

    • tabId

      число

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

    • timeStamp

      число

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onCommitted

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • transitionQualifiers

      TransitionQualifier[]

      Список условий перехода.

    • transitionType

      TransitionType

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onCompleted

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onCreatedNavigationTarget

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • sourceFrameId

      число

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

    • sourceProcessId

      число

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

    • sourceTabId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • url

      string

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

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onDOMContentLoaded

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onErrorOccurred

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • ошибка

      string

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

      Устарело начиная с Chrome 50

      Для этого события больше не задан идентификатор processId.

      Значение -1.

    • tabId

      число

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

    • timeStamp

      число

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onHistoryStateUpdated

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • transitionQualifiers

      TransitionQualifier[]

      Список условий перехода.

    • transitionType

      TransitionType

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onReferenceFragmentUpdated

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • documentId

      string

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • frameId

      число

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

      Тип фрейма, в котором произошел переход.

    • parentDocumentId

      Строка (необязательно)

      Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

    • parentFrameId

      число

      Chrome 74 и более поздних версий browser.* начиная с Chrome 148

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

    • processId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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

    • transitionQualifiers

      TransitionQualifier[]

      Список условий перехода.

    • transitionType

      TransitionType

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

    • url

      string

• фильтры

  Объект (необязательно)

  • url

    events.UrlFilter[]

    Условия, которым должен соответствовать URL, по которому выполняется переход.

onTabReplaced

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • replacedTabId

      число

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

    • tabId

      число

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

    • timeStamp

      число

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