Esta página foi traduzida pela API Cloud Translation.

API de cache de avanço e retorno notRestoredReasons

Descubra quais navegações não podem usar o bfcache e o motivo disso.

Chris Mills

Barry Pollard

A propriedade notRestoredReasons, adicionada à classe PerformanceNavigationTiming, informa se os frames presentes no documento foram impedidos de usar o bfcache na navegação e o motivo. Os desenvolvedores podem usar essas informações para identificar as páginas que precisam de atualizações para torná-las compatíveis com o bfcache, melhorando a performance do site.

Status atual

A API notRestoredReasons foi enviada do Chrome 123 e está sendo lançada gradualmente.

Conceitos e uso

Os navegadores modernos oferecem um recurso de otimização para navegação histórica chamado cache de avanço e retorno (bfcache). Isso permite uma experiência de carregamento instantâneo quando os usuários voltam a uma página que já visitaram. As páginas podem ser impedidas de entrar no bfcache ou serem removidas enquanto estiverem no bfcache por diferentes motivos, alguns exigidos por uma especificação e outros específicos para implementações do navegador.

Antes, os desenvolvedores não tinham como descobrir por que as páginas eram impedidas de usar o bfcache em campo, embora houvesse um teste nas ferramentas para desenvolvedores do Chrome. Para ativar o monitoramento em campo, a classe PerformanceNavigationTiming foi estendida para incluir uma propriedade notRestoredReasons. Isso retorna um objeto que contém informações relacionadas no frame superior e todos os iframes presentes no documento:

Motivos para o bloqueio de uso do bfcache.
Detalhes como frame id e name, para ajudar a identificar iframes no HTML.

Isso permite que os desenvolvedores tomem medidas para tornar essas páginas compatíveis com o bfcache, melhorando o desempenho do site.

Exemplos

Uma instância PerformanceNavigationTiming pode ser recebida de recursos como Performance.getEntriesByType() e PerformanceObserver.

Por exemplo, você pode invocar a seguinte função para retornar todos os objetos PerformanceNavigationTiming presentes na linha do tempo de desempenho e registrar os 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);
  }
}

Para navegações históricas, a propriedade PerformanceNavigationTiming.notRestoredReasons retorna um objeto com a estrutura abaixo, que representa o estado bloqueado do frame de nível superior:

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

As propriedades são as seguintes:

children: Uma matriz de objetos que representam o estado bloqueado de qualquer frame de mesma origem incorporado no frame de nível superior. Cada objeto tem a mesma estrutura que o objeto pai. Dessa forma, qualquer número de níveis de frames incorporados pode ser representado dentro do objeto de maneira recursiva. Se o frame não tiver filhos, a matriz ficará vazia.
id: Uma string que representa o valor do atributo id do frame (por exemplo, <iframe id="foo" src="...">). Se o frame não tiver id, o valor será null. Para a página de nível superior, é null.
name: Uma string que representa o valor do atributo name do frame (por exemplo, <iframe name="bar" src="...">). Se o frame não tiver name, o valor será uma string vazia. Para a página de nível superior, é null.
reasons: Uma matriz de strings, cada uma representando um motivo pelo qual a página navegada foi impedida de usar o bfcache. Há vários motivos para o bloqueio ocorrer. Consulte a seção Motivos de bloqueio para mais detalhes.
src: Uma string que representa o caminho para a origem do frame (por exemplo, <iframe src="b.html">). Se o frame não tiver src, o valor será uma string vazia. Para a página de nível superior, é null.
url: Uma string que representa o URL da página/iframe navegada.

Para objetos PerformanceNavigationTiming que não representam navegações do histórico, a propriedade notRestoredReasons vai retornar null.

Observe que notRestoredReasons também retorna null quando não há motivos de bloqueio. Portanto, ser null não é um indicador de que o bfcache foi ou não usado. Para isso, use a propriedade event.persisted.

Informar bloqueio de bfcache em frames de mesma origem

Quando uma página tem frames de mesma origem incorporados, o valor notRestoredReasons retornado vai conter um objeto dentro da propriedade children, representando o estado bloqueado de cada frame incorporado.

Exemplo:

{
  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"
}

Informar bloqueio de bfcache em frames de origem cruzada

Quando uma página tem frames de origem cruzada incorporados, limitamos a quantidade de informações compartilhadas sobre eles para evitar o vazamento de informações. Incluímos apenas informações que a página externa já conhece e se a subárvore de origem cruzada bloqueou o bfcache ou não. Não incluímos motivos de bloqueio ou informações sobre os níveis mais baixos da subárvore (mesmo que alguns subníveis sejam da mesma origem).

Exemplo:

{
  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"
}

Para todos os iframes de origem cruzada, informamos null para o valor reasons do frame, e o frame de nível superior mostra o motivo de "masked". "masked" também pode ser usado para motivos específicos do user agent. Por isso, nem sempre indica um problema em um iframe.

Consulte a seção Segurança e privacidade da explicação para mais detalhes sobre as considerações de segurança e privacidade.

Motivos de bloqueio

Como dissemos anteriormente, há muitos motivos diferentes pelos quais o bloqueio pode ocorrer:

Confira a seguir exemplos de alguns dos motivos mais comuns pelos quais o bfcache não pode ser usado:

unload-listener: a página registra um gerenciador unload, que impede o uso do bfcache em determinados navegadores. Consulte Como suspender o uso do evento de descarregamento para mais informações.
response-cache-control-no-store: a página usa no-store como um valor cache-control.
related-active-contents: a página foi aberta em outra página (usando "guia duplicada") que ainda tem uma referência a ela.

Feedback

A equipe do Chromium quer saber mais sobre suas experiências com a API bfcache notRestoredReasons.

Fale sobre o design da API

Existe algo na API que não funciona como você esperava? Ou faltam métodos ou propriedades que você precisa para implementar sua ideia? Tem uma pergunta ou comentário sobre o modelo de segurança? Registre um problema de especificação no repositório do GitHub (link em inglês) correspondente ou adicione sua opinião a um problema.

Informar um problema com a implementação

Você encontrou um bug na implementação do Chromium? Ou a implementação é diferente das especificações? Registre um bug no nosso Issue Tracker. Inclua o máximo de detalhes possível, instruções simples para reprodução e especifique o componente como UI > Browser > Navigation > BFCache. O Glitch é ótimo para compartilhar repetições rápidas e fáceis.

Mostrar suporte à API

Você planeja usar a API notRestoredReasons do bfcache? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostrar a outros fornecedores de navegadores como é fundamental oferecer suporte a eles.

Envie um tweet para @ChromiumDev usando a hashtag #NotRestoredReasons e informe onde e como você a está usando.