Quando uma transição de visualização é executada em um único documento, ela é chamada de transição de visualização do mesmo documento. Isso normalmente ocorre em aplicativos de página única (SPAs) em que o JavaScript é usado para atualizar o DOM. As transições de visualização do mesmo documento estão disponíveis no Chrome a partir do Chrome 111.
Para acionar uma transição de visualização do mesmo documento, chame document.startViewTransition
:
function handleClick(e) {
// Fallback for browsers that don't support this API:
if (!document.startViewTransition) {
updateTheDOMSomehow();
return;
}
// With a View Transition:
document.startViewTransition(() => updateTheDOMSomehow());
}
Quando invocado, o navegador captura automaticamente snapshots de todos os elementos que têm uma propriedade CSS view-transition-name
declarada neles.
Em seguida, ele executa o retorno de chamada transmitido que atualiza o DOM. Depois, ele cria snapshots do novo estado.
Esses instantâneos são organizados em uma árvore de pseudoelementos e animados com o poder das animações CSS. Os pares de snapshots do estado antigo e novo fazem uma transição suave da posição e do tamanho antigos para o novo local, enquanto o conteúdo deles se cruza. Se quiser, use CSS para personalizar as animações.
A transição padrão: cross-fade
A transição de visualização padrão é um cross-fade, portanto, serve como uma boa introdução à API:
function spaNavigate(data) {
// Fallback for browsers that don't support this API:
if (!document.startViewTransition) {
updateTheDOMSomehow(data);
return;
}
// With a transition:
document.startViewTransition(() => updateTheDOMSomehow(data));
}
Em que updateTheDOMSomehow
muda o DOM para o novo estado. Você pode fazer isso como quiser. Por exemplo, é possível adicionar ou remover elementos, mudar nomes de classes ou estilos.
Assim, as páginas fazem a transição cruzada:
Ok, um cross-fade não é tão impressionante. Felizmente, é possível personalizar as transições, mas primeiro você precisa entender como esse cross-fade básico funciona.
Como essas transições funcionam
Vamos atualizar o exemplo de código anterior.
document.startViewTransition(() => updateTheDOMSomehow(data));
Quando .startViewTransition()
é chamado, a API captura o estado atual da página. Isso inclui criar um snapshot.
Depois de concluído, o callback transmitido para .startViewTransition()
é chamado. É aqui que o DOM é alterado. Em seguida, a API captura o novo estado da página.
Depois que o novo estado é capturado, a API constrói uma árvore de pseudoelementos como esta:
::view-transition
└─ ::view-transition-group(root)
└─ ::view-transition-image-pair(root)
├─ ::view-transition-old(root)
└─ ::view-transition-new(root)
O ::view-transition
fica em uma sobreposição, sobre todo o restante na página. Isso é útil se você deseja definir uma cor de fundo para a transição.
::view-transition-old(root)
é uma captura de tela da visualização antiga, e ::view-transition-new(root)
é uma representação ao vivo da nova visualização. Ambos são renderizados como "conteúdo substituído" de CSS (como um <img>
).
A visualização antiga é animada de opacity: 1
para opacity: 0
, enquanto a nova visualização é animada de opacity: 0
para opacity: 1
, criando um cross-fade.
Toda a animação é realizada usando animações CSS, para que possam ser personalizadas com CSS.
Personalizar a transição
Todos os pseudoelementos de transição de visualização podem ser segmentados com CSS e, como as animações são definidas com CSS, é possível modificá-las usando as propriedades de animação CSS existentes. Exemplo:
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 5s;
}
Com essa mudança, a esmaecimento fica bem lenta:
Ok, isso ainda não é impressionante. Em vez disso, o código abaixo implementa a transição de eixo compartilhado do Material Design:
@keyframes fade-in {
from { opacity: 0; }
}
@keyframes fade-out {
to { opacity: 0; }
}
@keyframes slide-from-right {
from { transform: translateX(30px); }
}
@keyframes slide-to-left {
to { transform: translateX(-30px); }
}
::view-transition-old(root) {
animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}
::view-transition-new(root) {
animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}
E aqui está o resultado:
Transição de vários elementos
Na demonstração anterior, a página inteira estava envolvida na transição do eixo compartilhado. Isso funciona na maior parte da página, mas não parece correto para o título, já que ele desliza para fora para deslizar de novo.
Para evitar isso, você pode extrair o cabeçalho do resto da página para que ele possa ser animado separadamente. Isso é feito atribuindo um view-transition-name
ao elemento.
.main-header {
view-transition-name: main-header;
}
O valor de view-transition-name
pode ser o que você quiser, exceto none
, que significa que não há nome de transição. Ele é usado para identificar de forma exclusiva o elemento na transição.
E o resultado disso:
Agora, o cabeçalho permanece no lugar e faz a transição gradual.
Essa declaração CSS fez a árvore de pseudoelementos mudar:
::view-transition
├─ ::view-transition-group(root)
│ └─ ::view-transition-image-pair(root)
│ ├─ ::view-transition-old(root)
│ └─ ::view-transition-new(root)
└─ ::view-transition-group(main-header)
└─ ::view-transition-image-pair(main-header)
├─ ::view-transition-old(main-header)
└─ ::view-transition-new(main-header)
Agora há dois grupos de transição. Um para o cabeçalho e outro para o restante. Elas podem ser segmentadas de forma independente com o CSS e receber diferentes transições. No entanto, nesse caso, a main-header
ficou com a transição padrão, que é um cross-fade.
Certo, a transição padrão não é apenas um cross-fade, o ::view-transition-group
também faz a transição:
- Posicionar e transformar (usando um
transform
) - Largura
- Altura
Isso não era importante até agora, já que o cabeçalho tem o mesmo tamanho e posiciona os dois lados da mudança do DOM. Mas você também pode extrair o texto do cabeçalho:
.main-header-text {
view-transition-name: main-header-text;
width: fit-content;
}
fit-content
é usado para que o elemento fique do tamanho do texto, em vez de se estender até a largura restante. Sem isso, a seta para trás reduz o tamanho do elemento de texto do cabeçalho, em vez do mesmo tamanho nas duas páginas.
Agora, temos três partes para testar:
::view-transition
├─ ::view-transition-group(root)
│ └─ …
├─ ::view-transition-group(main-header)
│ └─ …
└─ ::view-transition-group(main-header-text)
└─ …
Mas vamos continuar com os valores padrão:
Agora o texto do título desliza um pouco para deixar espaço para o botão "Voltar".
Animar vários pseudoelementos da mesma forma com view-transition-class
Compatibilidade com navegadores
- 125
- 125
- x
- x
Digamos que você tenha uma transição de visualização com vários cards, mas também um título na página. Para animar todos os cards, exceto o título, crie um seletor que segmente cada um deles individualmente.
h1 {
view-transition-name: title;
}
::view-transition-group(title) {
animation-timing-function: ease-in-out;
}
#card1 { view-transition-name: card1; }
#card2 { view-transition-name: card2; }
#card3 { view-transition-name: card3; }
#card4 { view-transition-name: card4; }
…
#card20 { view-transition-name: card20; }
::view-transition-group(card1),
::view-transition-group(card2),
::view-transition-group(card3),
::view-transition-group(card4),
…
::view-transition-group(card20) {
animation-timing-function: var(--bounce);
}
Você tem 20 elementos? São 20 seletores que você precisa escrever. Adicionando um novo elemento? Em seguida, você também precisa aumentar o seletor que aplica os estilos de animação. Não é exatamente escalonável.
O view-transition-class
pode ser usado nos pseudoelementos de transição de visualização para aplicar a mesma regra de estilo.
#card1 { view-transition-name: card1; }
#card2 { view-transition-name: card2; }
#card3 { view-transition-name: card3; }
#card4 { view-transition-name: card4; }
#card5 { view-transition-name: card5; }
…
#card20 { view-transition-name: card20; }
#cards-wrapper > div {
view-transition-class: card;
}
html::view-transition-group(.card) {
animation-timing-function: var(--bounce);
}
O exemplo de cards a seguir usa o snippet de CSS anterior. Todos os cartões, incluindo os recém-adicionados, recebem o mesmo tempo com um seletor: html::view-transition-group(.card)
.
Depurar transições
Como as transições de visualização são criadas com base nas animações CSS, o painel Animations no Chrome DevTools é ótimo para depurar transições.
No painel Animações, você pode pausar a próxima animação e depois deslizar para frente e para trás nela. Durante isso, os pseudoelementos de transição podem ser encontrados no painel Elementos.
Os elementos de transição não precisam ser o mesmo elemento DOM
Até agora, usamos view-transition-name
para criar elementos de transição separados para o cabeçalho e o texto nele. Conceitualmente, trata-se do mesmo elemento antes e depois da mudança do DOM, mas você pode criar transições quando isso não acontecer.
Por exemplo, a incorporação do vídeo principal pode receber um view-transition-name
:
.full-embed {
view-transition-name: full-embed;
}
Então, quando a miniatura receber um clique, ela poderá receber o mesmo view-transition-name
, apenas durante a transição:
thumbnail.onclick = async () => {
thumbnail.style.viewTransitionName = 'full-embed';
document.startViewTransition(() => {
thumbnail.style.viewTransitionName = '';
updateTheDOMSomehow();
});
};
E o resultado:
A miniatura passa para a imagem principal. Embora sejam elementos conceitualmente (e literalmente) diferentes, a API de transição os trata como a mesma coisa, porque compartilham o mesmo view-transition-name
.
O código real para essa transição é um pouco mais complicado do que o exemplo anterior, porque também lida com a transição de volta para a página de miniatura. Consulte a origem para ver a implementação completa.
Transições personalizadas de entrada e saída
Confira este exemplo:
A barra lateral faz parte da transição:
.sidebar {
view-transition-name: sidebar;
}
Mas, diferente do cabeçalho do exemplo anterior, a barra lateral não aparece em todas as páginas. Se os dois estados tiverem a barra lateral, os pseudoelementos de transição ficarão assim:
::view-transition
├─ …other transition groups…
└─ ::view-transition-group(sidebar)
└─ ::view-transition-image-pair(sidebar)
├─ ::view-transition-old(sidebar)
└─ ::view-transition-new(sidebar)
No entanto, se a barra lateral estiver apenas na nova página, o pseudoelemento ::view-transition-old(sidebar)
não estará lá. Como não há uma imagem "antiga" na barra lateral, o par de imagens terá apenas uma ::view-transition-new(sidebar)
. Da mesma forma, se a barra lateral estiver apenas na página antiga, o par de imagens terá apenas um ::view-transition-old(sidebar)
.
Na demonstração anterior, a barra lateral faz a transição de maneira diferente, dependendo se está entrando, saindo ou presente nos dois estados. Ela entra deslizando da direita e desaparecendo, sai deslizando para a direita e desaparece e permanece no lugar quando está presente nos dois estados.
Para criar transições específicas de entrada e saída, use a pseudoclasse :only-child
(link em inglês) para direcionar os pseudoelementos antigos ou novos quando eles forem o único filho no par de imagens:
/* Entry transition */
::view-transition-new(sidebar):only-child {
animation: 300ms cubic-bezier(0, 0, 0.2, 1) both fade-in,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}
/* Exit transition */
::view-transition-old(sidebar):only-child {
animation: 150ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-right;
}
Nesse caso, não há uma transição específica para quando a barra lateral estiver presente nos dois estados, já que o padrão é perfeito.
Atualizações assíncronas do DOM e espera por conteúdo
O callback transmitido para .startViewTransition()
pode retornar uma promessa, que permite atualizações assíncronas do DOM e espera que o conteúdo importante esteja pronto.
document.startViewTransition(async () => {
await something;
await updateTheDOMSomehow();
await somethingElse;
});
A transição não será iniciada até que a promessa for atendida. Durante esse período, a página fica congelada. Por isso, o tempo de espera deve ser mínimo. Especificamente, as buscas de rede precisam ser feitas antes de chamar .startViewTransition()
, enquanto a página ainda está totalmente interativa, em vez de fazer isso como parte do callback .startViewTransition()
.
Se você decidir esperar até que imagens ou fontes fiquem prontas, use um tempo limite agressivo:
const wait = ms => new Promise(r => setTimeout(r, ms));
document.startViewTransition(async () => {
updateTheDOMSomehow();
// Pause for up to 100ms for fonts to be ready:
await Promise.race([document.fonts.ready, wait(100)]);
});
No entanto, em alguns casos, é melhor evitar totalmente esse atraso e usar o conteúdo que você já tem.
Aproveite ao máximo o conteúdo que você já tem
No caso em que a miniatura muda para uma imagem maior:
A transição padrão é o esmaecimento cruzado, o que significa que a miniatura pode passar por esmaecimento cruzado com uma imagem completa ainda não carregada.
Uma maneira de lidar com isso é aguardar o carregamento da imagem completa antes de iniciar a transição. O ideal seria fazer isso antes de chamar .startViewTransition()
, para que a página permaneça interativa, e um ícone de carregamento poderá ser mostrado para indicar ao usuário que as coisas estão sendo carregadas. Mas, neste caso, há uma maneira melhor:
::view-transition-old(full-embed),
::view-transition-new(full-embed) {
/* Prevent the default animation,
so both views remain opacity:1 throughout the transition */
animation: none;
/* Use normal blending,
so the new view sits on top and obscures the old view */
mix-blend-mode: normal;
}
A miniatura não desaparece, ela fica apenas abaixo da imagem inteira. Isso significa que, se a nova visualização não tiver sido carregada, a miniatura vai ficar visível durante a transição. Isso significa que a transição pode começar imediatamente e que a imagem completa pode ser carregada no próprio tempo.
Isso não funcionaria se a nova visualização tivesse transparência, mas neste caso sabemos que não tem, então podemos fazer essa otimização.
Gerenciar mudanças na proporção
Convenientemente, todas as transições até agora foram para elementos com a mesma proporção, mas nem sempre será assim. E se a miniatura for 1:1 e a imagem principal for 16:9?
Na transição padrão, o grupo é animado do tamanho anterior para o posterior. As visualizações antigas e novas têm 100% de largura do grupo e altura automática, o que significa que elas mantêm a proporção, independentemente do tamanho do grupo.
Esse é um bom padrão, mas não é o que queremos neste caso. Portanto:
::view-transition-old(full-embed),
::view-transition-new(full-embed) {
/* Prevent the default animation,
so both views remain opacity:1 throughout the transition */
animation: none;
/* Use normal blending,
so the new view sits on top and obscures the old view */
mix-blend-mode: normal;
/* Make the height the same as the group,
meaning the view size might not match its aspect-ratio. */
height: 100%;
/* Clip any overflow of the view */
overflow: clip;
}
/* The old view is the thumbnail */
::view-transition-old(full-embed) {
/* Maintain the aspect ratio of the view,
by shrinking it to fit within the bounds of the element */
object-fit: contain;
}
/* The new view is the full image */
::view-transition-new(full-embed) {
/* Maintain the aspect ratio of the view,
by growing it to cover the bounds of the element */
object-fit: cover;
}
Isso significa que a miniatura permanece no centro do elemento à medida que a largura se expande, mas a imagem completa é "descortada" à medida que muda de 1:1 para 16:9.
Para informações mais detalhadas, consulte (Transições de visualização: como processar mudanças de proporção)(https://jakearchibald.com/2024/view-transitions-handling-aspect-ratio-Changes/)
Usar consultas de mídia para alterar transições para diferentes estados do dispositivo
Você pode usar transições diferentes no dispositivo móvel e no computador, como este exemplo que executa um slide completo na lateral no dispositivo móvel, mas um slide mais sutil no computador:
Isso pode ser conseguido usando consultas de mídia regulares:
/* Transitions for mobile */
::view-transition-old(root) {
animation: 300ms ease-out both full-slide-to-left;
}
::view-transition-new(root) {
animation: 300ms ease-out both full-slide-from-right;
}
@media (min-width: 500px) {
/* Overrides for larger displays.
This is the shared axis transition from earlier in the article. */
::view-transition-old(root) {
animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}
::view-transition-new(root) {
animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}
}
Também é possível mudar quais elementos você atribui a uma view-transition-name
, dependendo das consultas de mídia correspondentes.
Reagir à preferência de "movimento reduzido"
Os usuários podem indicar que preferem usar o movimento reduzido no sistema operacional e que essa preferência é exposta no CSS.
Você pode optar por impedir qualquer transição para esses usuários:
@media (prefers-reduced-motion) {
::view-transition-group(*),
::view-transition-old(*),
::view-transition-new(*) {
animation: none !important;
}
}
No entanto, uma preferência por "movimento reduzido" não significa que o usuário não quer nenhum movimento. Em vez do snippet anterior, você pode escolher uma animação mais sutil, mas que ainda expresse a relação entre os elementos e o fluxo de dados.
Processar vários estilos de transição de visualização com os tipos de transição
Às vezes, uma transição de uma visualização específica para outra precisa ter uma transição especificamente adaptada. Por exemplo, ao ir para a próxima página ou para a anterior em uma sequência de paginação, você pode deslizar o conteúdo em uma direção diferente, dependendo se está indo para uma página mais alta ou mais baixa na sequência.
Para isso, você pode usar os tipos de transição de visualização, que permitem atribuir um ou mais tipos a uma transição de visualização ativa. Por exemplo, ao fazer a transição para uma página superior em uma sequência de paginação, use o tipo forwards
e, ao acessar uma página inferior, use o tipo backwards
. Esses tipos só ficam ativos ao capturar ou realizar uma transição, e cada tipo pode ser personalizado com CSS para usar animações diferentes.
Para usar tipos em uma transição de visualização do mesmo documento, transmita types
para o método startViewTransition
. Para permitir isso, document.startViewTransition
também aceita um objeto: update
é a função de callback que atualiza o DOM, e types
é uma matriz com os tipos.
const direction = determineBackwardsOrForwards();
const t = document.startViewTransition({
update: updateTheDOMSomehow,
types: ['slide', direction],
});
.
Para responder a esses tipos, use o seletor :active-view-transition-type()
. Transmita o type
que você quer segmentar para o seletor. Isso permite manter os estilos de várias transições de visualização separados uns dos outros, sem que as declarações de uma interfiram nas declarações da outra.
Como os tipos só se aplicam ao capturar ou realizar a transição, você pode usar o seletor para definir ou cancelar a definição de uma view-transition-name
em um elemento somente para a transição de visualização com esse tipo.
/* 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 (using the default root snapshot) */
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;
}
}
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. Os tipos são determinados ao clicar em que são transmitidos para document.startViewTransition
.
Para segmentar qualquer transição de visualização ativa, independente do tipo, use o seletor de pseudoclasse :active-view-transition
.
html:active-view-transition {
…
}
Processar vários estilos de transição de visualização com um nome de classe na raiz da transição de visualização
Às vezes, uma transição de um tipo específico de visualização para outro precisa ter uma transição especificamente adaptada. Ou uma navegação "voltar" é diferente de uma navegação "avançar".
Antes dos tipos de transição, a forma de lidar com esses casos era definir temporariamente um nome de classe na raiz de transição. Ao chamar document.startViewTransition
, essa raiz de transição é o elemento <html>
, que pode ser acessado usando document.documentElement
em JavaScript:
if (isBackNavigation) {
document.documentElement.classList.add('back-transition');
}
const transition = document.startViewTransition(() =>
updateTheDOMSomehow(data)
);
try {
await transition.finished;
} finally {
document.documentElement.classList.remove('back-transition');
}
Para remover as classes após o término da transição, este exemplo usa transition.finished
, uma promessa que é resolvida quando a transição atinge o estado final. Outras propriedades desse objeto são abordadas na Referência da API.
Agora você pode usar esse nome de classe no seu CSS para alterar a transição:
/* 'Forward' transitions */
::view-transition-old(root) {
animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}
::view-transition-new(root) {
animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in, 300ms
cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}
/* Overrides for 'back' transitions */
.back-transition::view-transition-old(root) {
animation-name: fade-out, slide-to-right;
}
.back-transition::view-transition-new(root) {
animation-name: fade-in, slide-from-left;
}
Assim como nas consultas de mídia, a presença dessas classes também pode ser usada para mudar quais elementos recebem um view-transition-name
.
Executar transições sem congelar outras animações
Confira esta demonstração de uma posição em transição de vídeo:
Você notou algo de errado? Não se preocupe se não foi. Aqui ela está mais lenta:
Durante a transição, o vídeo parece congelar, e a versão em reprodução aparece gradualmente. Isso ocorre porque ::view-transition-old(video)
é uma captura de tela da visualização antiga, enquanto ::view-transition-new(video)
é uma imagem ativa da nova visualização.
Você pode corrigir isso, mas primeiro, pergunte a si mesmo se vale a pena corrigir isso. Se você não viu o "problema" quando a transição estava sendo reproduzida na velocidade normal, não mudaria.
Se você quiser corrigir o problema, não mostre a ::view-transition-old(video)
. Mude diretamente para a ::view-transition-new(video)
. Para fazer isso, substitua os estilos e as animações padrão:
::view-transition-old(video) {
/* Don't show the frozen old view */
display: none;
}
::view-transition-new(video) {
/* Don't fade the new view in */
animation: none;
}
Pronto.
Agora, o vídeo é reproduzido durante a transição.
Animar com JavaScript
Até agora, todas as transições foram definidas usando CSS, mas às vezes o CSS não é suficiente:
Algumas partes dessa transição não podem ser realizadas apenas com CSS:
- A animação começa no local do clique.
- A animação termina com o círculo tendo um raio até o canto mais distante. No entanto, esperamos que isso seja possível com o CSS no futuro.
Felizmente, é possível criar transições usando a API Web Animation.
let lastClick;
addEventListener('click', event => (lastClick = event));
function spaNavigate(data) {
// Fallback for browsers that don't support this API:
if (!document.startViewTransition) {
updateTheDOMSomehow(data);
return;
}
// Get the click position, or fallback to the middle of the screen
const x = lastClick?.clientX ?? innerWidth / 2;
const y = lastClick?.clientY ?? innerHeight / 2;
// Get the distance to the furthest corner
const endRadius = Math.hypot(
Math.max(x, innerWidth - x),
Math.max(y, innerHeight - y)
);
// With a transition:
const transition = document.startViewTransition(() => {
updateTheDOMSomehow(data);
});
// Wait for the pseudo-elements to be created:
transition.ready.then(() => {
// Animate the root's new view
document.documentElement.animate(
{
clipPath: [
`circle(0 at ${x}px ${y}px)`,
`circle(${endRadius}px at ${x}px ${y}px)`,
],
},
{
duration: 500,
easing: 'ease-in',
// Specify which pseudo-element to animate
pseudoElement: '::view-transition-new(root)',
}
);
});
}
Esse exemplo usa transition.ready
, uma promessa que é resolvida quando os pseudoelementos da transição são criados. Outras propriedades desse objeto são abordadas na Referência da API.
Transições como um aprimoramento
A API View Transition foi projetada para "unir" uma mudança DOM e criar uma transição para ela. No entanto, a transição deve ser tratada como um aprimoramento, por exemplo, seu aplicativo não deverá entrar em um estado de "erro" se a alteração do DOM for bem-sucedida, mas a transição falhar. O ideal é que a transição não falhe, mas, se isso acontecer, ela não deve interromper o restante da experiência do usuário.
Para tratar as transições como uma melhoria, tome cuidado para não usar promessas de transição de uma forma que faça com que seu app seja gerado se a transição falhar.
async function switchView(data) { // Fallback for browsers that don't support this API: if (!document.startViewTransition) { await updateTheDOM(data); return; } const transition = document.startViewTransition(async () => { await updateTheDOM(data); }); await transition.ready; document.documentElement.animate( { clipPath: [`inset(50%)`, `inset(0)`], }, { duration: 500, easing: 'ease-in', pseudoElement: '::view-transition-new(root)', } ); }
O problema com esse exemplo é que switchView()
vai ser rejeitada se a transição não alcançar um estado ready
, mas isso não significa que a visualização falhou ao mudar. O DOM pode ter sido atualizado, mas havia view-transition-name
s duplicados, então a transição foi ignorada.
Como alternativa:
async function switchView(data) { // Fallback for browsers that don't support this API: if (!document.startViewTransition) { await updateTheDOM(data); return; } const transition = document.startViewTransition(async () => { await updateTheDOM(data); }); animateFromMiddle(transition); await transition.updateCallbackDone; } async function animateFromMiddle(transition) { try { await transition.ready; document.documentElement.animate( { clipPath: [`inset(50%)`, `inset(0)`], }, { duration: 500, easing: 'ease-in', pseudoElement: '::view-transition-new(root)', } ); } catch (err) { // You might want to log this error, but it shouldn't break the app } }
Este exemplo usa transition.updateCallbackDone
para aguardar a atualização do DOM e rejeitar se ela falhar. O switchView
não será mais rejeitado se a transição falhar. Ele será resolvido quando a atualização do DOM for concluída e será rejeitado se falhar.
Se você quiser que switchView
resolva quando a nova visualização for "definida", como em qualquer transição animada concluída ou ignorada para o final, substitua transition.updateCallbackDone
por transition.finished
.
Não é um polyfill, mas...
Esse não é um recurso fácil de usar o polyfill. No entanto, essa função auxiliar facilita muito esse processo em navegadores que não têm suporte a transições de visualização:
function transitionHelper({
skipTransition = false,
types = [],
update,
}) {
const unsupported = (error) => {
const updateCallbackDone = Promise.resolve(update()).then(() => {});
return {
ready: Promise.reject(Error(error)),
updateCallbackDone,
finished: updateCallbackDone,
skipTransition: () => {},
types,
};
}
if (skipTransition || !document.startViewTransition) {
return unsupported('View Transitions are not supported in this browser');
}
try {
const transition = document.startViewTransition({
update,
types,
});
return transition;
} catch (e) {
return unsupported('View Transitions with types are not supported in this browser');
}
}
E ela pode ser usada assim:
function spaNavigate(data) {
const types = isBackNavigation ? ['back-transition'] : [];
const transition = transitionHelper({
update() {
updateTheDOMSomehow(data);
},
types,
});
// …
}
Em navegadores que não oferecem suporte a transições de visualização, updateDOM
ainda será chamado, mas não haverá uma transição animada.
Você também pode fornecer alguns classNames
para adicionar a <html>
durante a transição, facilitando a mudança, dependendo do tipo de navegação.
Você também pode transmitir true
para skipTransition
se não quiser uma animação, mesmo em navegadores compatíveis com transições de visualização. Isso será útil se o site tiver preferência por desativar as transições.
Como trabalhar com frameworks
Se você estiver trabalhando com uma biblioteca ou framework que abstraia as alterações do DOM, a parte complicada é saber quando a alteração do DOM foi concluída. Veja um conjunto de exemplos usando o auxiliar acima em vários frameworks.
- Reagir: a chave aqui é
flushSync
, que aplica um conjunto de mudanças de estado de forma síncrona. Sim, há um grande aviso sobre o uso dessa API, mas Dan Abramov garante que é apropriado nesse caso. Como de costume com o React e o código assíncrono, ao usar as várias promessas retornadas porstartViewTransition
, verifique se o código está sendo executado com o estado correto. - Vue.js: a chave aqui é
nextTick
, que é atendida quando o DOM é atualizado. - Svelte: muito semelhante ao Vue, mas o método para aguardar a próxima mudança é
tick
(link em inglês). - Lit: a chave aqui é a promessa
this.updateComplete
nos componentes, que será atendida quando o DOM for atualizado. - Angular: chave aqui é
applicationRef.tick
, que limpa alterações pendentes do DOM. A partir da versão 17 do Angular, é possível usarwithViewTransitions
que vem com@angular/router
.
Referência da API
const viewTransition = document.startViewTransition(update)
Inicie uma nova
ViewTransition
.update
é uma função chamada quando o estado atual do documento é capturado.Depois, quando a promessa retornada por
updateCallback
for atendida, a transição vai começar no próximo frame. Se a promessa retornada porupdateCallback
for rejeitada, a transição será abandonada.const viewTransition = document.startViewTransition({ update, types })
Iniciar uma nova
ViewTransition
com os tipos especificadosO
update
é chamado quando o estado atual do documento é capturado.types
define os tipos ativos para a transição ao capturar ou realizar a transição. Inicialmente, está vazio. ConsulteviewTransition.types
mais abaixo para mais informações.
Membros da instância de ViewTransition
:
viewTransition.updateCallbackDone
Uma promessa que será atendida quando a promessa retornada por
updateCallback
for atendida ou rejeitada quando for rejeitada.A API View Transition encapsula uma mudança do DOM e cria uma transição. No entanto, às vezes você não se importa com o sucesso ou a falha da animação de transição, mas deseja saber se e quando a mudança do DOM acontece.
updateCallbackDone
é para esse caso de uso.viewTransition.ready
Uma promessa que será atendida quando os pseudoelementos da transição forem criados e a animação estiver prestes a começar.
Ela será rejeitada se a transição não puder começar. Isso pode ocorrer devido a uma configuração incorreta, como
view-transition-name
s duplicados ou seupdateCallback
retornar uma promessa recusada.Isso é útil para animar os pseudoelementos de transição com JavaScript.
viewTransition.finished
Uma promessa que será atendida quando o estado final estiver totalmente visível e interativo para o usuário.
Ela só será rejeitada se
updateCallback
retornar uma promessa recusada, porque isso indica que o estado final não foi criado.Caso contrário, se uma transição não for iniciada ou for ignorada durante a transição, o estado final ainda será atingido, então
finished
será atendido.viewTransition.types
Um objeto semelhante a
Set
(link em inglês) que contém os tipos da transição do Active View. Para manipular as entradas, use os métodos de instância deleclear()
,add()
edelete()
.Para responder a um tipo específico em CSS, use o seletor de pseudoclasse
:active-view-transition-type(type)
na raiz de transição.Os tipos são limpos automaticamente quando a transição de visualização é concluída.
viewTransition.skipTransition()
Pule a parte de animação da transição.
Ele não pulará a chamada de
updateCallback
, já que a mudança do DOM é separada da transição.
Estilo padrão e referência de transição
::view-transition
- O pseudoelemento raiz que preenche a janela de visualização e contém cada
::view-transition-group
. ::view-transition-group
Absolutamente posicionado.
Transições
width
eheight
entre os estados "antes" e "depois".Transições
transform
entre os quadrados do espaço da janela de visualização "antes" e "depois".::view-transition-image-pair
Absolutamente posicionado para preencher o grupo.
Tem
isolation: isolate
para limitar o efeito domix-blend-mode
nas visualizações antigas e novas.::view-transition-new
e::view-transition-old
Absolutamente posicionado no canto superior esquerdo do wrapper.
Preenche 100% da largura do grupo, mas tem uma altura automática para manter a proporção em vez de preencher o grupo.
Tem
mix-blend-mode: plus-lighter
para permitir um cross-fade real.A visualização antiga faz a transição de
opacity: 1
paraopacity: 0
. A nova visualização faz a transição deopacity: 0
paraopacity: 1
.
Feedback
O feedback dos desenvolvedores é sempre bem-vindo. Para fazer isso, registre um problema com o CSS Working Group no GitHub com sugestões e perguntas. Adicione o prefixo [css-view-transitions]
ao problema.
Se ocorrer um bug, registre um bug do Chromium.