chrome.webNavigation (original) (raw)

Przejdź do głównej treści

• Dokumenty

  • Przegląd
  • Rozpocznij
  • Rozwój współpracy
  • Poradniki
  • AI
  • Materiały referencyjne
  • Sample
  • Chrome Web Store

• Studia przypadków

• Blog

• Nowości w Chrome

• Manifest V3

• ➡ Manifest V2

• accessibilityFeatures

• action

• alarms

• audio

• bookmarks

• browsingData

• certificateProvider

• commands

• contentSettings

• contextMenus

• cookies

• debugger

• declarativeContent

• declarativeNetRequest

• desktopCapture

• devtools.inspectedWindow

• devtools.network

• devtools.panels

• devtools.performance

• devtools.recorder

• dns

• documentScan

• dom

• downloads

• enterprise.deviceAttributes

• enterprise.hardwarePlatform

• enterprise.login

• enterprise.networkingAttributes

• enterprise.platformKeys

• events

• extension

• extensionTypes

• fileBrowserHandler

• fileSystemProvider

• fontSettings

• gcm

• history

• i18n

• identity

• idle

• input.ime

• instanceID

• loginState

• management

• notifications

• offscreen

• omnibox

• pageCapture

• permissions

• platformKeys

• power

• printerProvider

• printing

• printingMetrics

• privacy

• processes

• proxy

• readingList

• runtime

• scripting

• search

• sessions

• sidePanel

• storage

• system.cpu

• system.display

• system.memory

• system.storage

• systemLog

• tabCapture

• tabGroups

• tabs

• topSites

• tts

• ttsEngine

• types

• userScripts

• vpnProvider

• wallpaper

• webAuthenticationProxy

• webNavigation

• webRequest

• windows

chrome.webNavigation

Opis

Używaj interfejsu chrome.webNavigation API, aby otrzymywać powiadomienia o stanie żądań nawigacyjnych w trakcie lotu.

Uprawnienia

webNavigation

Wszystkie metody i zdarzenia chrome.webNavigation wymagają zadeklarowania uprawnienia "webNavigation" w pliku manifestu rozszerzenia. Na przykład:

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

Pojęcia i zastosowanie

Kolejność wydarzeń

W przypadku pomyślnego zakończenia nawigacji zdarzenia są wywoływane w tej kolejności:

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

Każdy błąd, który wystąpi podczas tego procesu, powoduje zdarzenie onErrorOccurred. W przypadku konkretnej nawigacji po zdarzeniu onErrorOccurred nie są wywoływane żadne inne zdarzenia.

Jeśli ramka nawigacyjna zawiera ramki podrzędne, zdarzenie onCommitted jest wywoływane przed zdarzeniem onBeforeNavigate dowolnej z ramek podrzędnych, a zdarzenie onCompleted jest wywoływane po zdarzeniu onCompleted wszystkich ramek podrzędnych.

Jeśli fragment referencyjny ramki zostanie zmieniony, zostanie wywołane zdarzenie onReferenceFragmentUpdated. To zdarzenie może zostać wywołane w dowolnym momencie po onDOMContentLoaded, nawet po onCompleted.

Jeśli interfejs History API jest używany do modyfikowania stanu ramki (np. za pomocą history.pushState()), wywoływane jest zdarzenie onHistoryStateUpdated. To zdarzenie może zostać wywołane w dowolnym momencie po onDOMContentLoaded.

Jeśli nawigacja przywróciła stronę z pamięci podręcznej stanu strony internetowej, zdarzenie onDOMContentLoaded nie zostanie wywołane. Zdarzenie nie jest wywoływane, ponieważ treść została już wczytana, gdy strona została odwiedzona po raz pierwszy.

Jeśli nawigacja została wywołana za pomocą Chrome Instant lub Instant Pages, w bieżącej karcie zostanie umieszczona w pełni wczytana strona. W takim przypadku uruchamiane jest zdarzenie onTabReplaced.

Związek ze zdarzeniami webRequest

Nie ma określonej kolejności zdarzeń interfejsu webRequest API i zdarzeń interfejsu webNavigation API. Może się zdarzyć, że zdarzenia webRequest są nadal odbierane w przypadku ramek, które rozpoczęły już nową nawigację, lub że nawigacja jest kontynuowana dopiero po pełnym załadowaniu zasobów sieciowych.

Ogólnie rzecz biorąc, zdarzenia webNavigation są ściśle powiązane ze stanem nawigacji wyświetlanym w interfejsie, a zdarzenia webRequest odpowiadają stanowi stosu sieciowego, który jest zwykle niedostępny dla użytkownika.

Identyfikatory kart

Nie wszystkie karty nawigacyjne odpowiadają rzeczywistym kartom w interfejsie Chrome, np. karta, która jest wstępnie renderowana. Takie karty nie są dostępne za pomocą interfejsu Tabs API ani nie można o nich uzyskać informacji, wywołując webNavigation.getFrame() lub webNavigation.getAllFrames(). Po przełączeniu takiej karty wywoływane jest zdarzenie onTabReplaced, a karta staje się dostępna za pomocą tych interfejsów API.

Sygnatury czasowe

Pamiętaj, że pewne techniczne osobliwości w sposobie obsługi przez system operacyjny odrębnych procesów Chrome mogą powodować rozbieżności między zegarem w samej przeglądarce a zegarem w procesach rozszerzeń. Oznacza to, że właściwość timeStamp zdarzenia WebNavigation jest wewnętrznie spójna.timeStamp Porównanie jednego zdarzenia z innym zdarzeniem da prawidłowe przesunięcie między nimi, ale porównanie ich z bieżącym czasem w rozszerzeniu (np. za pomocą (new Date()).getTime()) może dać nieoczekiwane wyniki.

Identyfikatory ramek

Ramki na karcie można identyfikować za pomocą identyfikatora ramki. Identyfikator ramki głównej to zawsze 0, a identyfikatory ramek podrzędnych to liczby dodatnie. Gdy dokument zostanie utworzony w ramce, jego identyfikator ramki pozostaje stały przez cały okres jego istnienia. Od Chrome 49 ten identyfikator jest też stały przez cały czas istnienia ramki (w przypadku wielu nawigacji).

Ze względu na wieloprocesowy charakter Chrome karta może używać różnych procesów do renderowania źródła i miejsca docelowego strony internetowej. Dlatego jeśli nawigacja odbywa się w nowym procesie, możesz otrzymywać zdarzenia zarówno z nowej, jak i ze starej strony, dopóki nowa nawigacja nie zostanie zatwierdzona (tzn. dopóki nie zostanie wysłane zdarzenie onCommitted dla nowej głównej ramki). Innymi słowy, może istnieć więcej niż jedna oczekująca sekwencja zdarzeń webNavigation z tym samym frameId. Sekwencje można rozróżnić za pomocą klawisza processId.

Pamiętaj też, że podczas tymczasowego ładowania proces może być kilkakrotnie przełączany. Dzieje się tak, gdy obciążenie jest przekierowywane do innej witryny. W takim przypadku będziesz otrzymywać powtarzające się zdarzenia onBeforeNavigate i onErrorOccurred, dopóki nie otrzymasz ostatecznego zdarzenia onCommitted.

Kolejną problematyczną kwestią w przypadku rozszerzeń jest cykl życia ramki. Ramka zawiera dokument (powiązany z zatwierdzonym adresem URL). Dokument może się zmieniać (np. w wyniku nawigacji), ale frameId pozostaje bez zmian, więc trudno jest powiązać zdarzenie w konkretnym dokumencie tylko z frameId. Wprowadzamy pojęcie documentId, czyli unikalnego identyfikatora dokumentu. Jeśli ramka zostanie przekierowana i otworzy nowy dokument, identyfikator ulegnie zmianie. To pole jest przydatne do określania, kiedy strony zmieniają stan cyklu życia (między wstępnym renderowaniem, aktywnością i pamięcią podręczną), ponieważ pozostaje niezmienione.

Typy i kwalifikatory przejść

Zdarzenie webNavigation onCommitted ma właściwości transitionType i transitionQualifiers. Typ przejścia jest taki sam jak w interfejsie history API i określa, jak przeglądarka przeszła do tego konkretnego adresu URL. Dodatkowo mogą być zwracane kwalifikatory przejścia, które dodatkowo definiują nawigację.

Istnieją te kwalifikatory przejścia:

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu webNavigation API z repozytorium chrome-extension-samples.

Typy

TransitionQualifier

Typ wyliczeniowy

"client_redirect"

„server_redirect”

„forward_back”

"from_address_bar"

TransitionType

Przyczyna nawigacji. Używane są te same typy przejść co w interfejsie History API. Są to te same typy przejść, które są zdefiniowane w interfejsie History API, z tym wyjątkiem, że zamiast "auto_toplevel" użyto "start_page" (dla zachowania zgodności wstecznej).

Typ wyliczeniowy

„link”

„typed”

"auto_bookmark"

„auto_subframe”

„manual_subframe”

„generated”

„start_page”

„form_submit”

„reload”

„keyword”

„keyword_generated”

Metody

getAllFrames()

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

Pobiera informacje o wszystkich ramkach danej karty.

Parametry

• Informacje o karcie, z której mają zostać pobrane wszystkie ramki.
  • Identyfikator karty.

Zwroty

• Promise<object[] | undefined>

getFrame()

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

Pobiera informacje o danej ramce. Ramka to element lub strony internetowej. Jest identyfikowana za pomocą identyfikatora karty i identyfikatora ramki.

Parametry

• Informacje o klatce, o której chcesz uzyskać informacje.
  • documentId
    string opcjonalny
    Identyfikator UUID dokumentu. Jeśli podano frameId lub tabId, zostaną one zweryfikowane pod kątem zgodności z dokumentem znalezionym na podstawie podanego identyfikatora dokumentu.
  • frameId
    number opcjonalny
    Identyfikator ramki na danej karcie.
  • processId
    number opcjonalny
    Ramki są teraz jednoznacznie identyfikowane przez identyfikator karty i identyfikator ramki. Identyfikator procesu nie jest już potrzebny, więc jest ignorowany.
    Identyfikator procesu, który uruchamia moduł renderujący dla tej karty.
  • Identyfikator karty, na której znajduje się ramka.

Zwroty

• Promise<object | undefined>

Wydarzenia

onBeforeNavigate

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

Uruchamiane, gdy ma nastąpić nawigacja.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w przypadku danej karty i procesu.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • W przypadku tego zdarzenia nie jest już ustawiany identyfikator procesu, ponieważ proces, który będzie renderować wynikowy dokument, nie jest znany do momentu wywołania funkcji onCommit.
        Wartość -1.
      • Identyfikator karty, na której ma nastąpić nawigacja.
      • Czas, w którym przeglądarka miała rozpocząć nawigację, w milisekundach od początku epoki.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onCommitted

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

Uruchamiane po zatwierdzeniu nawigacji. Dokument (i zasoby, do których się odwołuje, np. obrazy i podramki) może być nadal pobierany, ale przynajmniej część dokumentu została odebrana z serwera i przeglądarka zdecydowała się przełączyć na nowy dokument.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas zatwierdzenia przejścia na stronę w milisekundach od początku epoki.
      • Lista kwalifikatorów przejścia.
      • Przyczyna nawigacji.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onCompleted

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

Wysyłane, gdy dokument, w tym zasoby, do których się odwołuje, jest w pełni wczytany i zainicjowany.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas zakończenia wczytywania dokumentu w milisekundach od początku epoki.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onCreatedNavigationTarget

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

Wysyłane, gdy do obsługi nawigacji zostanie utworzone nowe okno lub nowa karta w istniejącym oknie.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator ramki z parametrem sourceTabId, w której uruchomiono nawigację. 0 oznacza główną ramkę.
      • Identyfikator procesu, który uruchamia mechanizm renderowania ramki źródłowej.
      • Identyfikator karty, na której uruchomiono nawigację.
      • Identyfikator karty, na której otwierany jest adres URL.
      • Czas, w którym przeglądarka miała utworzyć nowy widok, w milisekundach od początku epoki.
      • Adres URL, który ma zostać otwarty w nowym oknie.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onDOMContentLoaded

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

Występuje, gdy DOM strony jest w pełni utworzony, ale zasoby, do których się odwołuje, mogą nie być jeszcze wczytane.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas, w którym DOM strony został w pełni utworzony, w milisekundach od początku epoki.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onErrorOccurred

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

Uruchamiane, gdy wystąpi błąd i nawigacja zostanie przerwana. Może się tak zdarzyć, jeśli wystąpił błąd sieci lub użytkownik przerwał nawigację.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Opis błędu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • W przypadku tego zdarzenia identyfikator procesu nie jest już ustawiony.
        Wartość -1.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas wystąpienia błędu w milisekundach od początku epoki.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onHistoryStateUpdated

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

Wywoływane, gdy historia ramki została zaktualizowana do nowego adresu URL. Wszystkie przyszłe wydarzenia w tej ramce będą korzystać ze zaktualizowanego adresu URL.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas zatwierdzenia przejścia na stronę w milisekundach od początku epoki.
      • Lista kwalifikatorów przejścia.
      • Przyczyna nawigacji.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onReferenceFragmentUpdated

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

Uruchamiane po zaktualizowaniu fragmentu referencyjnego klatki. Wszystkie przyszłe wydarzenia w tej ramce będą korzystać ze zaktualizowanego adresu URL.

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator UUID wczytanego dokumentu.
      • Cykl życia dokumentu.
      • Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramek są unikalne w obrębie karty.
      • Typ ramki, w której nastąpiła nawigacja.
      • parentDocumentId
        string opcjonalny
        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta wartość nie jest ustawiona.
      • Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.
      • Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.
      • Identyfikator karty, na której następuje nawigacja.
      • Czas zatwierdzenia przejścia na stronę w milisekundach od początku epoki.
      • Lista kwalifikatorów przejścia.
      • Przyczyna nawigacji.
• • Warunki, które musi spełniać adres URL, do którego następuje nawigacja. Pola „schemes” i „ports” w UrlFilter są ignorowane w przypadku tego zdarzenia.

onTabReplaced

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

Wywoływane, gdy zawartość karty zostanie zastąpiona inną kartą (zwykle wcześniej wstępnie wyrenderowaną).

Parametry

• Parametr callback wygląda tak:
  (details: object) => void
  • • Identyfikator karty, która została zastąpiona.
      • Identyfikator karty, która zastąpiła starą kartę.
      • Czas, w którym nastąpiła zamiana, w milisekundach od początku epoki.

O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.

Ostatnia aktualizacja: 2025-09-11 UTC.