Interfejs API stanu strony internetowej notRestoredReasons

Sprawdź, które nawigacje zostały zablokowane w korzystaniu z pamięci podręcznej typu „wstecz/do przodu” i dlaczego.

Chris Mills
Barry Pollard

Właściwość notRestoredReasons, dodana do klasy PerformanceNavigationTiming, raportuje informacje o tym, czy ramki obecne w dokumencie zostały zablokowane przed użyciem bfcache podczas nawigacji, oraz o przyczynach tego zablokowania. Dzięki tym informacjom deweloperzy mogą określić, które strony wymagają aktualizacji, aby były zgodne z pamięcią podręczną wstecz/do przodu, co poprawi wydajność witryny.

Obecny stan,

Interfejs notRestoredReasons API jest dostępny w Chrome 123 i jest wdrażany stopniowo.

Pojęcia i zastosowanie

Nowoczesne przeglądarki oferują funkcję optymalizacji nawigacji po historii o nazwie pamięć podręczna stanu strony internetowej (bfcache). Dzięki temu użytkownicy mogą natychmiast wczytać stronę, którą już odwiedzili. Strony mogą być blokowane przed wejściem do pamięci podręcznej lub usuwane z niej z różnych powodów. Niektóre z nich są wymagane przez specyfikację, a inne są specyficzne dla implementacji przeglądarki.

Wcześniej deweloperzy nie mieli możliwości sprawdzenia, dlaczego ich strony są blokowane przed używaniem pamięci podręcznej wstecz/do przodu w środowisku produkcyjnym, chociaż w narzędziach deweloperskich w Chrome był dostępny test. Aby włączyć monitorowanie w terenie, klasa PerformanceNavigationTiming została rozszerzona o właściwość notRestoredReasons. Zwraca obiekt zawierający powiązane informacje o głównej ramce i wszystkich elementach iframe w dokumencie:

  • Przyczyny zablokowania korzystania z pamięci podręcznej typu „wstecz/do przodu”.

  • Szczegóły, takie jak ramka id i name, które pomagają zidentyfikować elementy iframe w HTML-u.

    Dzięki temu deweloperzy mogą podejmować działania, aby dostosować te strony do pamięci podręcznej, co poprawia wydajność witryny.

Przykłady

Instancję PerformanceNavigationTiming można uzyskać z funkcji takich jak Performance.getEntriesByType() i PerformanceObserver.

Możesz na przykład wywołać tę funkcję, aby zwrócić wszystkie obiekty PerformanceNavigationTiming występujące na osi czasu wydajności i zarejestrować ich notRestoredReasons:

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 w historii właściwość PerformanceNavigationTiming.notRestoredReasons zwraca obiekt o tej strukturze, który reprezentuje stan zablokowania ramki najwyższego poziomu:

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

Właściwości:

children
Tablica obiektów reprezentujących stan zablokowania wszystkich ramek z tej samej domeny, które są zagnieżdżone w ramce najwyższego poziomu. Każdy obiekt ma taką samą strukturę jak obiekt nadrzędny. W ten sposób w obiekcie można rekursywnie przedstawić dowolną liczbę poziomów osadzonych ramek. Jeśli ramka nie ma elementów podrzędnych, tablica będzie pusta.
id
Ciąg znaków reprezentujący wartość atrybutu id ramki (np. <iframe id="foo" src="...">). Jeśli ramka nie ma atrybutu id, wartość będzie równa 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 atrybutu 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 przyczynę, dla której strona, na którą nastąpiło przejście, nie mogła użyć pamięci podręcznej typu „wstecz/do przodu”. Blokada 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 (np. <iframe src="b.html">). Jeśli ramka nie ma atrybutu src, wartością będzie pusty ciąg znaków. W przypadku strony najwyższego poziomu jest to null.
url
Ciąg znaków reprezentujący adres URL strony lub elementu iframe, do którego nastąpiło przejście.

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

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

Raportowanie blokowania pamięci podręcznej typu „wstecz/do przodu” w ramkach z tej samej domeny

Gdy strona zawiera zagnieżdżone ramki z tej samej domeny, zwrócona wartość notRestoredReasons będzie zawierać obiekt w właściwości children reprezentujący stan zablokowania każdej zagnieżdżonej 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"
}

Raportowanie blokowania pamięci podręcznej typu „wstecz/do przodu” w ramkach z innych domen

Gdy na stronie są osadzone ramki z innych domen, ograniczamy ilość udostępnianych informacji o nich, aby uniknąć wycieku informacji z innych domen. Udostępniamy tylko informacje, które są już znane stronie zewnętrznej, oraz informację, czy poddrzewo z innej domeny zablokowało pamięć podręczną typu „wstecz/do przodu”. Nie podajemy żadnych powodów blokowania ani informacji o niższych poziomach poddrzewa (nawet jeśli niektóre podpoziomy mają to samo pochodzenie).

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 z innej domeny w kolumnie reasons wyświetlamy wartość null, a w przypadku ramki najwyższego poziomu podajemy przyczynę "masked". Pamiętaj, że "masked" może być też używany z powodów związanych z przeglądarką, więc nie zawsze wskazuje na problem w ramce iframe.

Więcej informacji o kwestiach związanych z bezpieczeństwem i prywatnością znajdziesz w sekcji Bezpieczeństwo i prywatność w wyjaśnieniu.

Przyczyny blokowania

Jak wspomnieliśmy wcześniej, blokowanie może nastąpić z wielu różnych powodów:

Oto przykłady najczęstszych przyczyn, dla których nie można użyć pamięci podręcznej:

  • 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 Wycofywanie zdarzenia unload.
  • response-cache-control-no-store: strona używa wartości no-store jako cache-control.
  • related-active-contents: strona została otwarta z innej strony (za pomocą opcji „Zduplikuj kartę”), która nadal się do niej odnosi.

Prześlij opinię

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

Opisz projekt interfejsu API

Czy coś w API nie działa tak, jak oczekujesz? Czy brakuje metod lub właściwości, które są potrzebne do realizacji Twojego pomysłu? Masz pytania lub uwagi dotyczące modelu zabezpieczeń? Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.

Zgłaszanie problemu z implementacją

Czy udało Ci się znaleźć 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. Podaj jak najwięcej szczegółów, proste instrukcje odtwarzania i określ komponent jako UI > Browser > Navigation > BFCache.

Wyrażanie poparcia dla interfejsu API

Czy zamierzasz używać interfejsu API notRestoredReasons pamięci podręcznej wstecz/do przodu? Twoje publiczne wsparcie pomaga zespołowi Chromium określać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wspieranie.

Wyślij tweeta do @ChromiumDev z hasztagiem #NotRestoredReasons i napisz, gdzie i jak korzystasz z tej funkcji.

Przydatne linki