browser.webNavigation

Opis

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

Uprawnienia

webNavigation

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

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

Pojęcia i użycie

Kolejność zdarzeń

W przypadku pomyślnie zakończonej 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 do modyfikowania stanu ramki używany jest interfejs History API (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ż podczas pierwszej wizyty na stronie treści zostały już wczytane.

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

Związek ze zdarzeniami webRequest

Nie ma określonej kolejności zdarzeń interfejsu API webRequest i zdarzeń interfejsu API webNavigation. Możliwe, ż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 API kart ani nie można o nich uzyskać informacji, wywołując funkcje webNavigation.getFrame() lub webNavigation.getAllFrames(). Gdy taka karta zostanie zamieniona, uruchamiane jest zdarzenie onTabReplaced i staje się ona dostępna za pomocą tych interfejsów API.

Sygnatury czasowe

Pamiętaj, że pewne techniczne osobliwości w sposobie, w jaki system operacyjny obsługuje odrębne procesy 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 właściwości zdarzenia WebNavigation timeStamp jest tylko wewnętrznie spójna. Porównanie jednego zdarzenia z innym da prawidłową różnicę 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 zidentyfikować 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 okres 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. Jeśli więc 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 ramki głównej). Innymi słowy, może istnieć więcej niż jedna oczekująca sekwencja zdarzeń webNavigation z tym samym frameId. Sekwencje można odróżnić za pomocą klawisza processId.

Pamiętaj też, że podczas tymczasowego ładowania proces może być kilkakrotnie przełączany. Dzieje się tak, gdy wczytywanie 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 nie, 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 przejść i kwalifikatory

Zdarzenie webNavigation onCommitted ma właściwości transitionType i transitionQualifiers. Typ przejścia jest taki sam jak w interfejsie History API, który opisuje, jak przeglądarka przeszła do tego konkretnego adresu URL. Dodatkowo można zwrócić kilka kwalifikatorów przejścia, które dodatkowo definiują nawigację.

Dostępne są te kwalifikatory przejścia:

Kwalifikacje do przejściaOpis
„client_redirect”Podczas nawigacji nastąpiło co najmniej 1 przekierowanie spowodowane przez JavaScript lub metatagi odświeżania na stronie.
„server_redirect”Podczas nawigacji wystąpiło co najmniej 1 przekierowanie spowodowane przez nagłówki HTTP wysłane z serwera.
„forward_back”Użytkownik rozpoczął nawigację, używając przycisku Dalej lub Wstecz.
„from_address_bar”Użytkownik zainicjował nawigację z paska adresu (omniboksu).

Przykłady

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

Typy

TransitionQualifier

Chrome 44 lub nowsza

Typ wyliczeniowy

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 lub nowsza

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 tą różnicą, że zamiast "auto_toplevel" użyto "start_page" (ze względu na zgodność wsteczną).

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 na danej karcie.

Parametry

  • szczegóły

    obiekt

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

    • tabId

      liczba

      Identyfikator karty.

Zwroty

  • Promise<object[] | undefined>

    Chrome 93 lub nowszy

getFrame()

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

Pobiera informacje o danej ramce. Ramka to element <iframe> lub <frame> strony internetowej. Jest identyfikowana przez identyfikator karty i identyfikator ramki.

Parametry

  • szczegóły

    obiekt

    Informacje o ramce, o której chcesz uzyskać informacje.

    • documentId

      ciąg znaków opcjonalny

      Chrome 106 lub nowsza

      Identyfikator UUID dokumentu. Jeśli podano identyfikator 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

      Wycofane w Chrome 49

      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.

    • tabId

      number opcjonalny

      Identyfikator karty, na której znajduje się ramka.

Zwroty

  • Promise<object | undefined>

    Chrome 93 lub nowszy

Wydarzenia

onBeforeNavigate

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

Wywoływane, gdy ma nastąpić nawigacja.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        Wartość 0 oznacza, że nawigacja odbywa się w oknie treści karty, a wartość dodatnia oznacza nawigację w ramce podrzędnej. Identyfikatory ramki są unikalne dla danej karty i procesu.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Wycofane w Chrome 50

        W przypadku tego zdarzenia nie jest już ustawiany identyfikator procesu, ponieważ proces, który będzie renderować wynikowy dokument, jest znany dopiero po wywołaniu funkcji onCommit.

        Wartość –1.

      • tabId

        liczba

        Identyfikator karty, na której ma nastąpić nawigacja.

      • timeStamp

        liczba

        Czas, w którym przeglądarka miała rozpocząć nawigację, w milisekundach od początku epoki.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

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 ramki podrzędne) może być nadal pobierany, ale przynajmniej część dokumentu została odebrana z serwera, a przeglądarka zdecydowała się przełączyć na nowy dokument.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas zatwierdzenia nawigacji w milisekundach od początku epoki.

      • transitionQualifiers

        TransitionQualifier[]

        Lista kwalifikatorów przejścia.

      • transitionType

        TransitionType

        Przyczyna nawigacji.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onCompleted

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

Wywoływane, gdy dokument, w tym zasoby, do których się odnosi, jest w pełni załadowany i zainicjowany.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas, w którym dokument został wczytany, w milisekundach od początku epoki.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onCreatedNavigationTarget

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • sourceFrameId

        liczba

        Identyfikator ramki z parametrem sourceTabId, w której uruchomiono nawigację. 0 oznacza ramkę główną.

      • sourceProcessId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla ramki źródłowej.

      • sourceTabId

        liczba

        Identyfikator karty, na której uruchomiono nawigację.

      • tabId

        liczba

        Identyfikator karty, na której otwierany jest adres URL.

      • timeStamp

        liczba

        Czas, w którym przeglądarka miała utworzyć nowy widok, w milisekundach od początku epoki.

      • URL

        tekst

        Adres URL, który ma zostać otwarty w nowym oknie.

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onDOMContentLoaded

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas pełnego utworzenia DOM strony (w milisekundach od początku epoki).

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onErrorOccurred

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

Wywoływane, 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

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • błąd

        tekst

        Opis błędu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Wycofane w Chrome 50

        W przypadku tego zdarzenia identyfikator procesu nie jest już ustawiony.

        Wartość –1.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas wystąpienia błędu w milisekundach od początku epoki.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onHistoryStateUpdated

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas zatwierdzenia nawigacji w milisekundach od początku epoki.

      • transitionQualifiers

        TransitionQualifier[]

        Lista kwalifikatorów przejścia.

      • transitionType

        TransitionType

        Przyczyna nawigacji.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onReferenceFragmentUpdated

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

Wywoływane, gdy zaktualizowano fragment referencyjny klatki. Wszystkie przyszłe zdarzenia w tej ramce będą korzystać ze zaktualizowanego adresu URL.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        tekst

        Chrome 106 lub nowsza

        Identyfikator UUID załadowanego dokumentu.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • frameId

        liczba

        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 ramach karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której nastąpiła nawigacja.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • parentFrameId

        liczba

        Chrome 74 lub nowsza

        Identyfikator ramki nadrzędnej lub -1, jeśli jest to ramka główna.

      • processId

        liczba

        Identyfikator procesu, który uruchamia moduł renderujący dla tej ramki.

      • tabId

        liczba

        Identyfikator karty, na której następuje nawigacja.

      • timeStamp

        liczba

        Czas zatwierdzenia nawigacji w milisekundach od początku epoki.

      • transitionQualifiers

        TransitionQualifier[]

        Lista kwalifikatorów przejścia.

      • transitionType

        TransitionType

        Przyczyna nawigacji.

      • URL

        tekst

  • filtry

    obiekt opcjonalny

    • Warunki, które musi spełniać adres URL, do którego następuje nawigacja.

onTabReplaced

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • replacedTabId

        liczba

        Identyfikator karty, która została zastąpiona.

      • tabId

        liczba

        Identyfikator karty, która zastąpiła starą kartę.

      • timeStamp

        liczba

        Czas, w którym nastąpiła zamiana, w milisekundach od początku epoki.