Interfejs API stanu strony internetowej notRestoredReasons

Sprawdź, które nawigacje zostały zablokowane przed korzystaniem z bfcache, oraz dlaczego.

Chris Mills
Barry Pollard

Właściwość notRestoredReasons dodana do klasy PerformanceNavigationTiming zawiera informacje o tym, czy ramki w dokumencie zostały zablokowane przed korzystaniem z bfcache w ramach nawigacji, oraz o przyczynach takiej decyzji. Deweloperzy mogą używać tych informacji do identyfikowania stron, które wymagają aktualizacji, aby były zgodne z bfcache, co poprawia wydajność witryny.

Obecny stan,

Interfejs notRestoredReasons API jest dostępny od wersji Chrome 123 i jest wprowadzany stopniowo.

Pojęcia i zastosowanie

Nowoczesne przeglądarki oferują funkcję optymalizacji nawigacji w historii o nazwie pamięć podręczna stanu strony internetowej (bfcache). Dzięki temu strona wczytuje się natychmiast, gdy użytkownik wraca na już odwiedzoną stronę. Strony mogą być blokowane przed wejściem do pamięci podręcznej bfcache lub mogą być z niej usuwane z różnych powodów, w tym wymaganych przez specyfikację i specyficznych dla implementacji przeglądarki.

Wcześniej deweloperzy nie mieli możliwości sprawdzenia, dlaczego ich strony nie mogą korzystać z bfcache w polu, choć dostępny był test w narzędziach dla deweloperów w Chrome. Aby umożliwić monitorowanie w polu, klasa PerformanceNavigationTiming została rozszerzona o właściwość notRestoredReasons. Zwraca obiekt zawierający powiązane informacje o ramce nadrzędnej i wszystkich elementach iframe w dokumencie:

  • przyczyny, dla których użytkownicy nie mogą korzystać z bfcache;

  • Szczegóły takie jak ramka id i name, które ułatwiają identyfikację ramek iframe w kodzie HTML.

    Dzięki temu deweloperzy mogą podjąć działania, aby te strony były zgodne z bfcache, co poprawia wydajność witryny.

Przykłady

Wystąpienie PerformanceNavigationTiming można uzyskać z funkcji takich jak Performance.getEntriesByType() i PerformanceObserver.

Aby zwrócić wszystkie obiekty PerformanceNavigationTiming obecne na osi czasu skuteczności i zapisać ich notRestoredReasons, możesz na przykład wywołać tę funkcję:

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let i = 0; i < navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

W przypadku nawigacji po historii właściwość PerformanceNavigationTiming.notRestoredReasons zwraca obiekt o tej strukturze, który reprezentuje zablokowany stan ramki najwyższego poziomu:

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

Są to:

children
Tablica obiektów reprezentujących zablokowany stan dowolnych ramek tego samego pochodzenia umieszczonych w ramce najwyższego poziomu. Każdy obiekt ma taką samą strukturę jak obiekt nadrzędny – dzięki temu w obiekcie można reprezentować dowolną liczbę poziomów osadzonych ramek w drodze rekurencyjnej. Jeśli ramka nie ma elementów podrzędnych, tablica będzie pusta.
id
Ciąg znaków reprezentujący wartość atrybutu id ramki (na przykład <iframe id="foo" src="...">). Jeśli w ramce nie ma atrybutu id, jego wartość będzie null. W przypadku strony najwyższego poziomu jest to null.
name
Ciąg reprezentujący wartość atrybutu name klatki (na przykład <iframe name="bar" src="...">). Jeśli klatka nie ma atrybutu name, jego wartość będzie pustym ciągiem. W przypadku strony najwyższego poziomu jest to null.
reasons
Tablica ciągów znaków, z których każdy reprezentuje powód, dla którego strona nawigacyjna została zablokowana przed korzystaniem z bfcache. Blokowanie może nastąpić z wielu różnych powodów. Więcej informacji znajdziesz w sekcji Przyczyny blokowania.
src
Ciąg znaków reprezentujący ścieżkę do źródła ramki (na przykład <iframe src="b.html">). Jeśli w ramce nie ma elementu src, wartość będzie pustym ciągiem znaków. W przypadku strony najwyższego poziomu jest to null.
url
Ciąg znaków reprezentujący adres URL strony lub ramki iframe, do której nastąpiło przekierowanie.

W przypadku obiektów PerformanceNavigationTiming, które nie reprezentują nawigacji w historii, właściwość notRestoredReasons zwróci wartość null.

Pamiętaj, że notRestoredReasons zwraca też wartość null, gdy nie ma powodów do blokowania, więc wartość null nie wskazuje, czy pamięć podręczna bfcache została użyta, czy nie. W tym celu musisz użyć właściwości event.persisted.

zgłaszanie blokowania bfcache w ramach domen o tej samej nazwie,

Jeśli strona zawiera osadzone ramki z tego samego źródła, zwrócona wartość notRestoredReasons będzie zawierać obiekt w ramach właściwości children, który reprezentuje zablokowany stan każdej osadzonej ramki.

Na przykład:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

Zgłaszanie blokowania bfcache w ramach międzydomenowym

Gdy na stronie są osadzone ramki między domenami, ograniczamy ilość informacji udostępnianych na ich temat, aby uniknąć wycieku informacji między domenami. Uwzględniamy tylko informacje, które strona zewnętrzna już zna, oraz to, czy poddrzewie z innej domeny zablokowało bfcache. Nie uwzględniamy żadnych przyczyn blokowania ani informacji o niższych poziomach poddrzewa (nawet jeśli niektóre z nich należą do tego samego źródła).

Na przykład:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

W przypadku wszystkich ramek iframe między domenami w ramce na najwyższym poziomie podajemy wartość null dla parametru reasons, a jako powód podajemy "masked". Pamiętaj, że "masked" może być używany również ze względu na informacje w identyfikatorze użytkownika, więc nie zawsze wskazuje problem w ramce iframe.

Więcej informacji o bezpieczeństwie i prywatności znajdziesz w sekcji Bezpieczeństwo i prywatność w treściach informacyjnych.

Powody blokowania

Jak już wspomnieliśmy, blokowanie może być spowodowane wieloma czynnikami:

Oto kilka najczęstszych przyczyn, dla których nie można używać bfcache:

  • unload-listener: strona rejestruje moduł obsługi unload, który uniemożliwia korzystanie z pamięci bfcache w niektórych przeglądarkach. Więcej informacji znajdziesz w artykule Wycofanie zdarzenia unload.
  • response-cache-control-no-store: strona używa wartości no-store jako wartości cache-control.
  • related-active-contents: strona została otwarta z innej strony (za pomocą „zduplikowanej karty”), która nadal zawiera odwołanie do tej strony.

Prześlij opinię

Zespół Chromium chce poznać Twoje wrażenia związane z interfejsem API bfcache notRestoredReasons.

Poinformuj nas o projektowaniu interfejsu API

Czy coś w interfejsie API nie działa zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, których potrzebujesz do wdrożenia swojego pomysłu? Masz pytania lub uwagi dotyczące modelu bezpieczeństwa? Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.

Zgłaszanie problemów z implementacją

Czy znalazłeś błąd w implementacji Chromium? A może implementacja różni się od specyfikacji? Zgłoś błąd w naszym narzędziu do śledzenia problemów. Pamiętaj, aby podać jak najwięcej szczegółów, proste instrukcje odtwarzania problemu i wskazanie komponentu jako UI > Browser > Navigation > BFCache. Glitch to świetne narzędzie do szybkiego i łatwego udostępniania informacji o powtarzających się problemach.

Pokaż informacje o pomocy dotyczącej interfejsu API

Zamierzasz używać interfejsu API bfcache notRestoredReasons? Twoja publiczna pomoc pomaga zespołowi Chromium ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie.

Wyślij tweeta do @ChromiumDev, używając hashtaga #NotRestoredReasons, i podaj, gdzie i jak z niego korzystasz.

Przydatne linki