Эта страница переведена с помощью Cloud Translation API.

chrome.webNavigation

Описание

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

Разрешения

webNavigation

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

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

Концепции и использование

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

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

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

Любая ошибка, возникающая во время процесса, приводит к возникновению события onErrorOccurred . Для конкретного перехода дальнейшие события после onErrorOccurred не возникают.

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

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

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

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

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

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

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

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

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

Не все навигационные вкладки соответствуют реальным вкладкам в пользовательском интерфейсе Chrome, например, вкладкам, которые находятся в процессе предварительной отрисовки. Такие вкладки недоступны через API вкладок, и вы не можете запросить информацию о них с помощью методов webNavigation.getFrame() или webNavigation.getAllFrames() . После замены такой вкладки активируется событие onTabReplaced , и она становится доступна через эти API.

Временные метки

Важно отметить, что некоторые технические особенности обработки ОС отдельных процессов Chrome могут привести к смещению времени между самим браузером и процессами расширения. Это означает, что свойство timeStamp события WebNavigation гарантирует только внутреннюю согласованность. Сравнение одного события с другим даст вам timeStamp смещение между ними, но сравнение их с текущим временем внутри расширения (например, с помощью (new Date()).getTime() ) может привести к неожиданным результатам.

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

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

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

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

Ещё одна концепция, вызывающая проблемы с расширениями, — это жизненный цикл фрейма. Фрейм содержит документ (связанный с закреплённым URL-адресом). Документ может измениться (например, при навигации), но frameId останется неизменным, поэтому сложно связать какие-либо события в конкретном документе только с frameIds . Мы вводим концепцию documentId , который является уникальным идентификатором для каждого документа. При переходе по фрейму и открытии нового документа идентификатор изменится. Это поле полезно для определения того, когда страницы меняют своё состояние жизненного цикла (между pre-render, active и cached), поскольку оно остаётся неизменным.

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

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

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

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

Примеры

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

Типы

TransitionQualifier

Хром 44+

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

"client_redirect"

"server_redirect"

"вперед_назад"

"from_address_bar"

TransitionType

Хром 44+

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

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

"связь"

"напечатанный"

"авто_закладка"

"auto_subframe"

"manual_subframe"

"сгенерированный"

"стартовая_страница"

"form_submit"

"перезагрузка"

"ключевое слово"

"keyword_generated"

Методы

getAllFrames()

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

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

Параметры

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

Возврат

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

getFrame()

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

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

Параметры

подробности
объект
Информация о кадре, о котором требуется получить информацию.
- documentId
  строка необязательная
  Хром 106+
  UUID документа. Если указаны frameId и/или tabId, они будут проверены на соответствие документу, найденному по указанному идентификатору.
- frameId
  номер необязательный
  Идентификатор фрейма в данной вкладке.
- processId
  номер необязательный
  Не рекомендуется с Chrome 49
  Теперь фреймы однозначно идентифицируются по идентификатору вкладки и идентификатору фрейма; идентификатор процесса больше не нужен и поэтому игнорируется.
  Идентификатор процесса, который запускает рендерер для этой вкладки.
- tabId
  номер необязательный
  Идентификатор вкладки, в которой находится фрейм.

Возврат

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

События

onBeforeNavigate

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

Срабатывает перед началом навигации.

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 указывает на то, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны для данной вкладки и процесса.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Не рекомендуется с Chrome 50
    ProcessId больше не задается для этого события, поскольку процесс, который будет визуализировать результирующий документ, неизвестен до onCommit.
    Значение -1.
  - tabId
    число
    Идентификатор вкладки, в которой будет осуществляться навигация.
  - отметка времени
    число
    Время, когда браузер собирался начать навигацию, в миллисекундах с начала эпохи.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCommitted

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Идентификатор процесса, запускающего рендерер для этого кадра.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время завершения навигации в миллисекундах с начала эпохи.
  - transitionQualifiers
    TransitionQualifier []
    Список квалификаторов перехода.
  - тип перехода
    Тип перехода
    Причина навигации.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCompleted

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Идентификатор процесса, запускающего рендерер для этого кадра.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время завершения загрузки документа в миллисекундах с начала эпохи.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onCreatedNavigationTarget

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - sourceFrameId
    число
    Идентификатор фрейма с sourceTabId, в котором запускается навигация. 0 указывает на основной фрейм.
  - sourceProcessId
    число
    Идентификатор процесса, запускающего рендерер для исходного кадра.
  - sourceTabId
    число
    Идентификатор вкладки, в которой активируется навигация.
  - tabId
    число
    Идентификатор вкладки, в которой открыт URL-адрес
  - отметка времени
    число
    Время, когда браузер собирался создать новое представление, в миллисекундах с начала эпохи.
  - URL-адрес
    нить
    URL-адрес, который будет открыт в новом окне.
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onDOMContentLoaded

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Идентификатор процесса, запускающего рендерер для этого кадра.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время, когда DOM страницы был полностью построен, в миллисекундах с начала эпохи.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onErrorOccurred

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - ошибка
    нить
    Описание ошибки.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Не рекомендуется с Chrome 50
    ProcessId больше не установлен для этого события.
    Значение -1.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время возникновения ошибки в миллисекундах с начала эпохи.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onHistoryStateUpdated

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Идентификатор процесса, запускающего рендерер для этого кадра.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время завершения навигации в миллисекундах с начала эпохи.
  - transitionQualifiers
    TransitionQualifier []
    Список квалификаторов перехода.
  - тип перехода
    Тип перехода
    Причина навигации.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onReferenceFragmentUpdated

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    нить
    Хром 106+
    UUID загруженного документа.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Хром 106+
    Жизненный цикл документа.
  - frameId
    число
    0 означает, что навигация осуществляется в окне содержимого вкладки; положительное значение указывает на навигацию в подфрейме. Идентификаторы фреймов уникальны в пределах вкладки.
  - frameType
    extensionTypes.FrameType
    Хром 106+
    Тип фрейма, в котором произошла навигация.
  - parentDocumentId
    строка необязательная
    Хром 106+
    UUID родительского документа, владеющего этим фреймом. Не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Хром 74+
    Идентификатор родительского фрейма или -1 , если это основной фрейм.
  - processId
    число
    Идентификатор процесса, запускающего рендерер для этого кадра.
  - tabId
    число
    Идентификатор вкладки, в которой происходит навигация.
  - отметка времени
    число
    Время завершения навигации в миллисекундах с начала эпохи.
  - transitionQualifiers
    TransitionQualifier []
    Список квалификаторов перехода.
  - тип перехода
    Тип перехода
    Причина навигации.
  - URL-адрес
    нить
фильтры
объект необязательный
- URL-адрес
  events.UrlFilter []
  Условия, которым должен соответствовать URL-адрес, по которому осуществляется переход. Поля «схемы» и «порты» фильтра UrlFilter для этого события игнорируются.

onTabReplaced

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(details: object) => void
```
- подробности
  объект
  - replacementTabId
    число
    Идентификатор вкладки, которая была заменена.
  - tabId
    число
    Идентификатор вкладки, которая заменила старую вкладку.
  - отметка времени
    число
    Время, когда произошла замена, в миллисекундах с начала эпохи.

chrome.webNavigation Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Разрешения

Концепции и использование

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

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

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

Временные метки

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

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

Примеры

Типы

TransitionQualifier

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

TransitionType

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

Методы

getAllFrames()

Параметры

Возврат

getFrame()

Параметры

Возврат

События

onBeforeNavigate

Параметры

onCommitted

Параметры

onCompleted

Параметры

onCreatedNavigationTarget

Параметры

onDOMContentLoaded

Параметры

onErrorOccurred

Параметры

onHistoryStateUpdated

Параметры

onReferenceFragmentUpdated

Параметры

onTabReplaced

Параметры

chrome.webNavigation