chrome.webNavigation

refresh date: 2026-09-25 robots: noindex

Описание

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

Разрешения

webNavigation

Манифест

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

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

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

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

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

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

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

Событие onCommitted в webNavigation API имеет свойства 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 и более поздних версий;

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

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 и более поздних версий;

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

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

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

Параметры

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

    Объект

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

    • tabId

      число

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

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

    function необязательно

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

    (details?: object[]) => void

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

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

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

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • documentLifecycle
        Chrome 106 и более поздних версий.

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

      • errorOccurred

        Логическое значение

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

      • frameId

        число

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

      • frameType
        Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

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

      • processId

        число

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

      • url

        string

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

Возвраты

  • Promise<object[] | undefined>

    Chrome 93 и более поздних версий

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

getFrame()

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

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

Параметры

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

    Объект

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

    • documentId

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

      Chrome 106 и более поздних версий.

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

    • frameId

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

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

    • processId

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

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

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

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

    • tabId

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

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

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

    function необязательно

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

    (details?: object) => void

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

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

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

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • documentLifecycle
        Chrome 106 и более поздних версий.

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

      • errorOccurred

        Логическое значение

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

      • frameType
        Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

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

      • url

        string

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

Возвраты

  • Promise<object | undefined>

    Chrome 93 и более поздних версий

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

События

onBeforeNavigate

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

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

      • processId

        число

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

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

        Значение -1.

      • tabId

        число

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

      • timeStamp

        число

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

      • url

        string

  • фильтры

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

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

onCommitted

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • transitionQualifiers

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

      • transitionType

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

      • url

        string

  • фильтры

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

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

onCompleted

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • url

        string

  • фильтры

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

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

onCreatedNavigationTarget

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • sourceFrameId

        число

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

      • sourceProcessId

        число

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

      • sourceTabId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • url

        string

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

  • фильтры

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

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

onDOMContentLoaded

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • url

        string

  • фильтры

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

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

onErrorOccurred

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • ошибка

        string

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

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

        Значение -1.

      • tabId

        число

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

      • timeStamp

        число

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

      • url

        string

  • фильтры

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

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

onHistoryStateUpdated

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • transitionQualifiers

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

      • transitionType

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

      • url

        string

  • фильтры

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

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

onReferenceFragmentUpdated

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • documentId

        string

        Chrome 106 и более поздних версий.

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

      • Chrome 106 и более поздних версий.

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

      • frameId

        число

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

      • Chrome 106 и более поздних версий.

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

      • parentDocumentId

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

        Chrome 106 и более поздних версий.

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

      • parentFrameId

        число

        Chrome 74 и более поздних версий.

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

      • processId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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

      • transitionQualifiers

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

      • transitionType

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

      • url

        string

  • фильтры

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

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

onTabReplaced

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

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

Параметры

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

    function

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

    (details: object) => void

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

      Объект

      • replacedTabId

        число

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

      • tabId

        число

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

      • timeStamp

        число

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