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. Programiści mogą wykorzystać te informacje, aby zidentyfikować strony, które wymagają aktualizacji, aby zapewnić zgodność z pamięcią podręczną Bfcache, a tym samym zwiększyć wydajność witryny.

Obecny stan,

Interfejs notRestoredReasons API został wprowadzony z Chrome 123 i jest wdrażany stopniowo.

Pojęcia i zastosowanie

Nowoczesne przeglądarki oferują funkcję optymalizacji przeglądania historii zwaną pamięcią podręczną 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, ale 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 zablokowania dostępu do bfcache;

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

    Dzięki temu programiści mogą podjąć działania, aby strony były zgodne z pamięcią podręczną w pamięci podręcznej, a tym samym poprawiały 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 ramka nie ma atrybutu id, jego wartość będzie null. W przypadku strony najwyższego poziomu jest to null.
name
Ciąg znaków reprezentujący wartość atrybutu name ramki (np. <iframe name="bar" src="...">). Jeśli ramka nie ma parametru name, wartością będzie pusty ciąg znaków. 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 funkcja notRestoredReasons zwraca wartość null również wtedy, gdy nie ma powodów do blokowania, więc wartość null nie wskazuje na to, czy pamięć podręczna bfcache była używana, 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 te informacje, które strona zewnętrzna już zna, oraz informacje o tym, czy podrzędne drzewo z innej domeny blokuje element 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ści wyjaśniającej.

Przyczyny zablokowania

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 podręcznej stanu strony internetowej 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 na innej stronie (przy użyciu „zduplikowanej karty”), która nadal zawiera odniesienie do tej strony.

Prześlij opinię

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

Prześlij informacje o projektowaniu interfejsu API

Czy jest coś, co nie działa w interfejsie API zgodnie z oczekiwaniami? A może brakuje Ci metod lub właściwości, których potrzebujesz, by wdrożyć swój pomysł? 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ś/znalazłaś błąd w implementacji Chromium? A może implementacja różni się od specyfikacji? Zgłoś błąd w naszym narzędziu do rejestrowania 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

Czy zamierzasz korzystać z 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