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
Перечисление
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
Причина навигации. Используются те же типы переходов, что и в 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()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
): Promise<object[] | undefined>
Извлекает информацию обо всех фреймах заданной вкладки.
Параметры
-
подробные сведения
Объект
Информация о вкладке, с которой нужно получить все фреймы.
-
tabId
число
Идентификатор вкладки.
-
-
обратный вызов
function необязательно
Параметр
callbackвыглядит следующим образом:(details?: object[]) => void
-
подробные сведения
object[] необязательный
Список фреймов на указанной вкладке. Если идентификатор вкладки недействителен, возвращается значение null.
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
errorOccurred
Логическое значение
True, если последняя навигация в этом фрейме была прервана ошибкой, то есть было запущено событие onErrorOccurred.
-
frameId
число
Идентификатор фрейма. Значение 0 указывает на то, что это основной фрейм, а положительное значение – на идентификатор дочернего фрейма.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
url
string
URL, связанный с этим фреймом.
-
-
Возвраты
-
Promise<object[] | undefined>
Chrome 93 и более поздних версийОбъекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.
getFrame()
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 загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
errorOccurred
Логическое значение
True, если последняя навигация в этом фрейме была прервана ошибкой, то есть было запущено событие onErrorOccurred.
-
frameTypeChrome 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 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны для каждой вкладки и процесса.
-
Chrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
число
Идентификатор родительского фрейма или
-1, если это основной фрейм. -
число
Устарело начиная с Chrome 50Для этого события больше не задается processId, поскольку процесс, который будет отображать итоговый документ, неизвестен до onCommit.
Значение -1.
-
число
Идентификатор вкладки, на которой будет выполнена навигация.
-
число
Время, когда браузер должен был начать навигацию, в миллисекундах с начала эпохи.
-
string
-
-
-
Объект (необязательно)
-
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда навигация подтверждена. Документ и ресурсы, на которые он ссылается (например, изображения и субфреймы), могут все ещё скачиваться, но по крайней мере часть документа уже получена от сервера, и браузер решил перейти к новому документу.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время фиксации навигации в миллисекундах с начала эпохи.
-
transitionQualifiers
Список условий перехода.
-
transitionType
Причина навигации.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда документ, включая ресурсы, на которые он ссылается, полностью загружен и инициализирован.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время завершения загрузки документа в миллисекундах с начала эпохи UNIX.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда для навигации создается новое окно или новая вкладка в существующем окне.
Параметры
-
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
Объект
-
число
Идентификатор фрейма с sourceTabId, в котором запускается навигация. 0 указывает на основной фрейм.
-
число
Идентификатор процесса, который запускает отрисовку для исходного фрейма.
-
число
Идентификатор вкладки, в которой активирована навигация.
-
число
Идентификатор вкладки, в которой открыт URL.
-
число
Время, когда браузер собирался создать новое представление, в миллисекундах с начала эпохи.
-
string
URL, который будет открыт в новом окне.
-
-
-
Объект (необязательно)
-
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда DOM страницы полностью сформирована, но связанные ресурсы могут быть загружены не до конца.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время, когда DOM страницы была полностью построена, в миллисекундах с начала эпохи.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда возникает ошибка и навигация прерывается. Это может произойти из-за ошибки сети или если пользователь прервал навигацию.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
ошибка
string
Описание ошибки.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Устарело начиная с Chrome 50Для этого события больше не задан идентификатор processId.
Значение -1.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время, когда произошла ошибка, в миллисекундах с начала эпохи.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда в истории фрейма появляется новый URL. Все будущие мероприятия для этой рамки будут использовать обновленный URL.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время фиксации навигации в миллисекундах с начала эпохи.
-
transitionQualifiers
Список условий перехода.
-
transitionType
Причина навигации.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Срабатывает, когда обновляется фрагмент ссылки фрейма. Все будущие мероприятия для этой рамки будут использовать обновленный URL.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
documentId
string
Chrome 106 и более поздних версий.UUID загруженного документа.
-
documentLifecycleChrome 106 и более поздних версий.
Жизненный цикл, в котором находится документ.
-
frameId
число
0 означает, что переход происходит в окне контента вкладки, а положительное значение – что переход происходит в субфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
-
frameTypeChrome 106 и более поздних версий.
Тип фрейма, в котором произошел переход.
-
parentDocumentId
Строка (необязательно)
Chrome 106 и более поздних версий.UUID родительского документа, которому принадлежит этот фрейм. Если родительского ресурса нет, этот вариант не задан.
-
parentFrameId
число
Chrome 74 и более поздних версий.Идентификатор родительского фрейма или
-1, если это основной фрейм. -
processId
число
Идентификатор процесса, который запускает отрисовщик для этого фрейма.
-
tabId
число
Идентификатор вкладки, на которой выполняется навигация.
-
timeStamp
число
Время фиксации навигации в миллисекундах с начала эпохи.
-
transitionQualifiers
Список условий перехода.
-
transitionType
Причина навигации.
-
url
string
-
-
-
фильтры
Объект (необязательно)
-
url
Условия, которым должен соответствовать URL, по которому выполняется переход.
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Срабатывает, когда содержимое вкладки заменяется другой вкладкой (обычно предварительно отрисованной).
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
replacedTabId
число
Идентификатор замененной вкладки.
-
tabId
число
Идентификатор вкладки, которая заменила старую.
-
timeStamp
число
Время, когда произошла замена, в миллисекундах с начала эпохи.
-
-