Transições de visualização entre documentos para aplicativos com várias páginas

Quando ocorre uma transição de visualização entre dois documentos, isso é chamado de transição de visualização entre documentos. Isso geralmente acontece em aplicativos de várias páginas (MPA, na sigla em inglês). As transições de visualização entre documentos estão disponíveis no Chrome a partir do Chrome 126.

As transições de visualização entre documentos dependem dos mesmos princípios e elementos básicos das transições de visualização do mesmo documento, o que é muito intencional:

1. O navegador faz snapshots dos elementos com um view-transition-name exclusivo na página antiga e na nova.
2. O DOM é atualizado enquanto a renderização é suprimida.
3. E, finalmente, as transições usam animações CSS.

A diferença em relação às transições de visualização do mesmo documento é que, nas transições de visualização entre documentos, você não precisa chamar document.startViewTransition para iniciar uma transição de visualização. O acionador da transição de visualização de vários documentos é a navegação de mesma origem de uma página para outra, uma ação geralmente realizada pelo usuário no seu site ao clicar em um link.

Em outras palavras, não há uma API a ser chamada para iniciar uma transição de visualização entre dois documentos. No entanto, há duas condições que precisam ser atendidas:

• Os dois documentos precisam estar na mesma origem.
• As duas páginas precisam ativar a transição de visualização.

Essas duas condições são explicadas posteriormente neste documento.

---

As transições de visualização entre documentos são limitadas a navegações de mesma origem.

As transições de visualização entre documentos são limitadas apenas às navegações de mesma origem. Uma navegação é considerada de mesma origem se a origem das duas páginas participantes for a mesma.

A origem de uma página é uma combinação do esquema, do nome do host e da porta usados, conforme detalhado em web.dev (link em inglês).

Por exemplo, você pode fazer uma transição de visualização entre documentos ao navegar de developer.chrome.com para developer.chrome.com/blog, já que os dois são da mesma origem. Não é possível fazer essa transição ao navegar de developer.chrome.com para www.chrome.com porque os dois são de origem cruzada e do mesmo site.

---

As transições de visualização entre documentos são opcionais

Para fazer uma transição de visualização entre dois documentos, as duas páginas participantes precisam permitir isso. Isso é feito com a at-rule @view-transition no CSS.

Na at-rule @view-transition, defina o descritor navigation como auto para ativar as transições de visualização para navegações de mesma origem em documentos diferentes.

@view-transition {
  navigation: auto;
}

Ao definir o descritor navigation como auto, você permite que as transições de visualização aconteçam para os seguintes NavigationTypes:

• traverse
• push ou replace, se a ativação não foi iniciada pelo usuário pelos mecanismos de interface do navegador.

As navegações excluídas do auto incluem, por exemplo, navegar usando a barra de endereço do URL ou clicar em um favorito, assim como qualquer forma de atualização iniciada pelo usuário ou script.

Se uma navegação demorar muito (mais de quatro segundos, no caso do Chrome), a transição de visualização será ignorada com uma DOMException TimeoutError.

Demonstração das transições de visualização entre documentos

Confira a demonstração a seguir que usa transições de visualização para criar uma demonstração do Stack Navigator. Não há chamadas para document.startViewTransition() aqui. As transições de visualização são acionadas ao navegar de uma página para outra.

---

Personalizar transições de visualização entre documentos

Para personalizar as transições de visualização entre documentos, você pode usar alguns recursos da plataforma da Web.

• Os eventos pageswap e pagereveal
• Informações de ativação da navegação
• Bloqueio de renderização

Esses recursos não fazem parte da especificação da API View Transition, mas foram projetados para serem usados em conjunto com ela.

Os eventos pageswap e pagereveal

Para permitir que você personalize as transições de visualização entre documentos, a especificação HTML inclui dois novos eventos que podem ser usados: pageswap e pagereveal.

Esses dois eventos são disparados para cada navegação de mesma origem em documentos cruzados, independentemente de uma transição de visualização estar prestes a acontecer ou não. Se uma transição de visualização estiver prestes a acontecer entre as duas páginas, você poderá acessar o objeto ViewTransition usando a propriedade viewTransition nesses eventos.

• O evento pageswap é disparado antes da renderização do último frame de uma página. É possível usá-la para fazer alterações de última hora na página de saída, logo antes de os snapshots antigos serem criados.
• O evento pagereveal é disparado em uma página depois de ter sido inicializada ou reativada, mas antes da primeira oportunidade de renderização. Com ele, é possível personalizar a nova página antes que os novos snapshots sejam criados.

Por exemplo, é possível usar esses eventos para definir ou mudar rapidamente alguns valores de view-transition-name ou transmitir dados de um documento para outro gravando e lendo dados de sessionStorage para personalizar a transição de visualização antes da execução.

let lastClickX, lastClickY;
document.addEventListener('click', (event) => {
  if (event.target.tagName.toLowerCase() === 'a') return;
  lastClickX = event.clientX;
  lastClickY = event.clientY;
});

// Write position to storage on old page
window.addEventListener('pageswap', (event) => {
  if (event.viewTransition && lastClick) {
    sessionStorage.setItem('lastClickX', lastClickX);
    sessionStorage.setItem('lastClickY', lastClickY);
  }
});

// Read position from storage on new page
window.addEventListener('pagereveal', (event) => {
  if (event.viewTransition) {
    lastClickX = sessionStorage.getItem('lastClickX');
    lastClickY = sessionStorage.getItem('lastClickY');
  }
});

Se quiser, pule a transição nos dois eventos.

window.addEventListener("pagereveal", async (e) => {
  if (e.viewTransition) {
    if (goodReasonToSkipTheViewTransition()) {
      e.viewTransition.skipTransition();
    }
  }
}

O objeto ViewTransition em pageswap e pagereveal são dois objetos diferentes. Eles também lidam com as várias promessas de maneira diferente:

• pageswap: quando o documento é ocultado, o objeto ViewTransition antigo é ignorado. Quando isso acontece, viewTransition.ready é rejeitado e viewTransition.finished é resolvido.
• pagereveal: a promessa updateCallBack já foi resolvida. Você pode usar as promessas viewTransition.ready e viewTransition.finished.

---

Informações de ativação da navegação

Nos eventos pageswap e pagereveal, também é possível realizar ações com base nos URLs da página antiga e da nova.

Por exemplo, no MPA Stack Navigator, o tipo de animação a ser usado depende do caminho de navegação:

• Ao navegar da página de visão geral para uma página de detalhes, o novo conteúdo precisa deslizar da direita para a esquerda.
• Ao navegar da página de detalhes para a de visão geral, o conteúdo antigo precisa ser movido da esquerda para a direita.

Para fazer isso, você precisa de informações sobre a navegação que, no caso de pageswap, vai acontecer ou, no caso de pagereveal, que acabou de acontecer.

Para isso, os navegadores agora podem expor objetos NavigationActivation que contêm informações sobre a navegação de mesma origem. Esse objeto expõe o tipo de navegação usado, as entradas atuais e as finais do histórico de destino, conforme encontrado em navigation.entries() da API Navigation.

Em uma página ativada, é possível acessar o objeto por meio do navigation.activation. No evento pageswap, é possível acessar essa informação pelo e.activation.

Confira esta demonstração de perfis (link em inglês) que usa informações de NavigationActivation nos eventos pageswap e pagereveal para definir os valores view-transition-name nos elementos que precisam participar da transição de visualização.

Dessa forma, não é necessário decorar todos os itens da lista com um view-transition-name antecipadamente. Em vez disso, isso acontece no momento certo usando JavaScript, apenas nos elementos que precisam dele.

O código é este:

// OLD PAGE LOGIC
window.addEventListener('pageswap', async (e) => {
  if (e.viewTransition) {
    const targetUrl = new URL(e.activation.entry.url);

    // Navigating to a profile page
    if (isProfilePage(targetUrl)) {
      const profile = extractProfileNameFromUrl(targetUrl);

      // Set view-transition-name values on the clicked row
      document.querySelector(`#${profile} span`).style.viewTransitionName = 'name';
      document.querySelector(`#${profile} img`).style.viewTransitionName = 'avatar';

      // Remove view-transition-names after snapshots have been taken
      // (this to deal with BFCache)
      await e.viewTransition.finished;
      document.querySelector(`#${profile} span`).style.viewTransitionName = 'none';
      document.querySelector(`#${profile} img`).style.viewTransitionName = 'none';
    }
  }
});

// NEW PAGE LOGIC
window.addEventListener('pagereveal', async (e) => {
  if (e.viewTransition) {
    const fromURL = new URL(navigation.activation.from.url);
    const currentURL = new URL(navigation.activation.entry.url);

    // Navigating from a profile page back to the homepage
    if (isProfilePage(fromURL) && isHomePage(currentURL)) {
      const profile = extractProfileNameFromUrl(currentURL);

      // Set view-transition-name values on the elements in the list
      document.querySelector(`#${profile} span`).style.viewTransitionName = 'name';
      document.querySelector(`#${profile} img`).style.viewTransitionName = 'avatar';

      // Remove names after snapshots have been taken
      // so that we're ready for the next navigation
      await e.viewTransition.ready;
      document.querySelector(`#${profile} span`).style.viewTransitionName = 'none';
      document.querySelector(`#${profile} img`).style.viewTransitionName = 'none';
    }
  }
});

O código também é limpo depois de remover os valores view-transition-name após a execução da transição de visualização. Dessa forma, a página fica pronta para navegações sucessivas e também pode processar a travessia do histórico.

Para ajudar nisso, use essa função utilitária que define view-transition-names temporariamente.

const setTemporaryViewTransitionNames = async (entries, vtPromise) => {
  for (const [$el, name] of entries) {
    $el.style.viewTransitionName = name;
  }

  await vtPromise;

  for (const [$el, name] of entries) {
    $el.style.viewTransitionName = '';
  }
}

O código anterior agora pode ser simplificado da seguinte maneira:

// OLD PAGE LOGIC
window.addEventListener('pageswap', async (e) => {
  if (e.viewTransition) {
    const targetUrl = new URL(e.activation.entry.url);

    // Navigating to a profile page
    if (isProfilePage(targetUrl)) {
      const profile = extractProfileNameFromUrl(targetUrl);

      // Set view-transition-name values on the clicked row
      // Clean up after the page got replaced
      setTemporaryViewTransitionNames([
        [document.querySelector(`#${profile} span`), 'name'],
        [document.querySelector(`#${profile} img`), 'avatar'],
      ], e.viewTransition.finished);
    }
  }
});

// NEW PAGE LOGIC
window.addEventListener('pagereveal', async (e) => {
  if (e.viewTransition) {
    const fromURL = new URL(navigation.activation.from.url);
    const currentURL = new URL(navigation.activation.entry.url);

    // Navigating from a profile page back to the homepage
    if (isProfilePage(fromURL) && isHomePage(currentURL)) {
      const profile = extractProfileNameFromUrl(currentURL);

      // Set view-transition-name values on the elements in the list
      // Clean up after the snapshots have been taken
      setTemporaryViewTransitionNames([
        [document.querySelector(`#${profile} span`), 'name'],
        [document.querySelector(`#${profile} img`), 'avatar'],
      ], e.viewTransition.ready);
    }
  }
});

---

Aguardar o carregamento do conteúdo com o bloqueio de renderização

Em alguns casos, é recomendável suspender a primeira renderização de uma página até que um determinado elemento esteja presente no novo DOM. Isso evita a atualização flash e garante que o estado para o qual você está animando seja estável.

No <head>, defina um ou mais IDs de elementos que precisam estar presentes antes que a página seja renderizada pela primeira vez usando a seguinte metatag.

<link rel="expect" blocking="render" href="#section1">

Essa metatag significa que o elemento deve estar presente no DOM, e não que o conteúdo deve ser carregado. Por exemplo, no caso de imagens, a simples presença da tag <img> com o id especificado na árvore DOM é suficiente para que a condição seja avaliada como verdadeira. A imagem em si ainda pode estar carregando.

Antes de bloquear totalmente a renderização, esteja ciente de que a renderização incremental é um aspecto fundamental da Web, portanto, tenha cuidado ao optar por bloquear a renderização. O impacto do bloqueio de renderização precisa ser avaliado caso a caso. Por padrão, evite usar blocking=render, a menos que você possa medir e avaliar ativamente o impacto que ele tem sobre os usuários, medindo o impacto nas Core Web Vitals.

---

Conferir tipos de transição em transições de visualização entre documentos

As transições de visualização entre documentos também oferecem suporte a tipos de transição de visualização para personalizar as animações e quais elementos são capturados.

Por exemplo, ao ir para a próxima página ou para a anterior em uma paginação, você pode usar animações diferentes, dependendo se você está indo para uma página mais alta ou mais baixa na sequência.

Para definir esses tipos antecipadamente, adicione os tipos na at-rule @view-transition:

@view-transition {
  navigation: auto;
  types: slide, forwards;
}

Para definir os tipos rapidamente, use os eventos pageswap e pagereveal para manipular o valor de e.viewTransition.types.

window.addEventListener("pagereveal", async (e) => {
  if (e.viewTransition) {
    const transitionType = determineTransitionType(navigation.activation.from, navigation.activation.entry);
    e.viewTransition.types.add(transitionType);
  }
});

Os tipos não são transferidos automaticamente do objeto ViewTransition da página antiga para o objeto ViewTransition da nova. É necessário determinar o(s) tipo(s) a ser usado pelo menos na nova página para que as animações sejam executadas conforme o esperado.

Para responder a esses tipos, use o seletor de pseudoclasse :active-view-transition-type() da mesma forma que faria com as transições de visualização do mesmo documento.

/* Determine what gets captured when the type is forwards or backwards */
html:active-view-transition-type(forwards, backwards) {
  :root {
    view-transition-name: none;
  }
  article {
    view-transition-name: content;
  }
  .pagination {
    view-transition-name: pagination;
  }
}

/* Animation styles for forwards type only */
html:active-view-transition-type(forwards) {
  &::view-transition-old(content) {
    animation-name: slide-out-to-left;
  }
  &::view-transition-new(content) {
    animation-name: slide-in-from-right;
  }
}

/* Animation styles for backwards type only */
html:active-view-transition-type(backwards) {
  &::view-transition-old(content) {
    animation-name: slide-out-to-right;
  }
  &::view-transition-new(content) {
    animation-name: slide-in-from-left;
  }
}

/* Animation styles for reload type only */
html:active-view-transition-type(reload) {
  &::view-transition-old(root) {
    animation-name: fade-out, scale-down;
  }
  &::view-transition-new(root) {
    animation-delay: 0.25s;
    animation-name: fade-in, scale-up;
  }
}

Como os tipos se aplicam apenas a uma transição de visualização ativa, os tipos são limpos automaticamente quando uma transição de visualização é concluída. Por isso, os tipos funcionam bem com recursos como BFCache (em inglês).

Demonstração

Na demonstração de paginação a seguir, o conteúdo da página desliza para frente ou para trás com base no número da página acessada.

O tipo de transição a ser usado é determinado nos eventos pagereveal e pageswap analisando os URLs de entrada e saída.

const determineTransitionType = (fromNavigationEntry, toNavigationEntry) => {
  const currentURL = new URL(fromNavigationEntry.url);
  const destinationURL = new URL(toNavigationEntry.url);

  const currentPathname = currentURL.pathname;
  const destinationPathname = destinationURL.pathname;

  if (currentPathname === destinationPathname) {
    return "reload";
  } else {
    const currentPageIndex = extractPageIndexFromPath(currentPathname);
    const destinationPageIndex = extractPageIndexFromPath(destinationPathname);

    if (currentPageIndex > destinationPageIndex) {
      return 'backwards';
    }
    if (currentPageIndex < destinationPageIndex) {
      return 'forwards';
    }

    return 'unknown';
  }
};

Feedback

O feedback dos desenvolvedores é sempre bem-vindo. Para compartilhar, registre um problema com o grupo de trabalho do CSS no GitHub com sugestões e perguntas. Adicione o prefixo [css-view-transitions] ao problema. Se ocorrer um bug, registre um bug do Chromium.