Transitions d'affichage entre les documents pour les applications multipages

Bramus

Lorsqu'une transition de vue se produit entre deux documents différents, on parle de transition de vue entre documents. C'est généralement le cas dans les applications multipages (MPA). Les transitions de vue entre documents sont prises en charge dans Chrome à partir de la version 126.

Les transitions de vue entre documents reposent sur les mêmes blocs de construction et principes que les transitions de vue dans un même document. C'est tout à fait intentionnel :

1. Le navigateur prend des instantanés des éléments qui ont un view-transition-name unique sur l'ancienne et la nouvelle page.
2. Le DOM est mis à jour lorsque le rendu est supprimé.
3. Enfin, les transitions sont alimentées par des animations CSS.

Contrairement aux transitions de vue dans le même document, vous n'avez pas besoin d'appeler document.startViewTransition pour démarrer une transition de vue dans un autre document. Au lieu de cela, le déclencheur d'une transition de vue entre documents est une navigation de même origine d'une page à une autre, une action généralement effectuée par l'utilisateur de votre site Web en cliquant sur un lien.

En d'autres termes, il n'existe aucune API à appeler pour démarrer une transition de vue entre deux documents. Toutefois, deux conditions doivent être remplies :

• Les deux documents doivent exister sur la même origine.
• Les deux pages doivent activer la transition de vue.

Ces deux conditions sont expliquées plus loin dans ce document.

Les transitions de vue entre documents sont limitées aux navigations de même origine

Les transitions de vue entre documents sont limitées aux navigations de même origine. Une navigation est considérée comme étant de même origine si l'origine des deux pages participantes est la même.

L'origine d'une page est une combinaison du schéma, du nom d'hôte et du port utilisés, comme détaillé sur web.dev.

Par exemple, vous pouvez avoir une transition de vue entre documents lorsque vous passez de developer.chrome.com à developer.chrome.com/blog, car ils sont de même origine. Vous ne pouvez pas avoir cette transition lorsque vous passez de developer.chrome.com à www.chrome.com, car il s'agit de transitions multi-origines et sur le même site.

Les transitions de vue entre les documents sont activées par défaut

Pour qu'une transition de vue inter-documents ait lieu entre deux documents, les deux pages concernées doivent accepter cette option. Pour ce faire, utilisez la règle @@view-transition dans CSS.

Dans la règle @ @view-transition, définissez le descripteur navigation sur auto pour activer les transitions de vue pour les navigations multi-documents de même origine.

@view-transition {
  navigation: auto;
}

En définissant le descripteur navigation sur auto, vous autorisez les transitions de vue pour les NavigationType suivants :

• traverse
• push ou replace, si l'activation n'a pas été initiée par l'utilisateur via les mécanismes de l'UI du navigateur.

Les navigations exclues de auto sont, par exemple, la navigation à l'aide de la barre d'adresse URL ou le clic sur un favori, ainsi que toute forme de rechargement initié par l'utilisateur ou un script.

Si une navigation prend trop de temps (plus de quatre secondes dans le cas de Chrome), la transition de vue est ignorée avec un TimeoutError DOMException.

Démonstration des transitions de vue entre les documents

Consultez la démo suivante qui utilise les transitions de vue pour créer une démonstration de Stack Navigator. Ici, il n'y a aucun appel à document.startViewTransition(). Les transitions de vue sont déclenchées par la navigation d'une page à une autre.

Personnaliser les transitions de vue entre les documents

Pour personnaliser les transitions de vue entre les documents, vous pouvez utiliser certaines fonctionnalités de la plate-forme Web.

• Événements pageswap et pagereveal
• Informations sur l'activation de la navigation
• Blocage du rendu

Ces fonctionnalités ne font pas partie de la spécification de l'API View Transitions elle-même, mais sont conçues pour être utilisées conjointement.

Événements pageswap et pagereveal

Pour vous permettre de personnaliser les transitions d'affichage entre documents, la spécification HTML inclut deux nouveaux événements que vous pouvez utiliser : pageswap et pagereveal.

Ces deux événements sont déclenchés pour chaque navigation multidocument de même origine, qu'une transition de vue soit sur le point de se produire ou non. Si une transition de vue est sur le point de se produire entre les deux pages, vous pouvez accéder à l'objet ViewTransition à l'aide de la propriété viewTransition sur ces événements.

• L'événement pageswap se déclenche avant le rendu du dernier frame d'une page. Vous pouvez l'utiliser pour apporter des modifications de dernière minute à la page sortante, juste avant la prise des anciens instantanés.
• L'événement pagereveal se déclenche sur une page après son initialisation ou sa réactivation, mais avant la première opportunité de rendu. Il vous permet de personnaliser la nouvelle page avant que les nouveaux instantanés ne soient pris.

Par exemple, vous pouvez utiliser ces événements pour définir ou modifier rapidement certaines valeurs view-transition-name, ou pour transmettre des données d'un document à un autre en écrivant et en lisant des données à partir de sessionStorage afin de personnaliser la transition de vue avant son exécution.

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');
  }
});

Si vous le souhaitez, vous pouvez choisir d'ignorer la transition dans les deux événements.

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

L'objet ViewTransition dans pageswap et pagereveal sont deux objets différents. Ils gèrent également les différentes promesses différemment :

• pageswap : Une fois le document masqué, l'ancien objet ViewTransition est ignoré. Dans ce cas, viewTransition.ready est rejeté et viewTransition.finished est résolu.
• pagereveal : la promesse updateCallBack est déjà résolue à ce stade. Vous pouvez utiliser les promesses viewTransition.ready et viewTransition.finished.

Informations sur l'activation de la navigation

Dans les événements pageswap et pagereveal, vous pouvez également agir en fonction des URL des anciennes et nouvelles pages.

Par exemple, dans le navigateur de pile MPA, le type d'animation à utiliser dépend du chemin de navigation :

• Lorsque vous passez de la page "Vue d'ensemble" à une page de détails, le nouveau contenu doit glisser de la droite vers la gauche.
• Lorsque vous passez de la page d'informations à la page de présentation, l'ancien contenu doit glisser de gauche à droite.

Pour ce faire, vous avez besoin d'informations sur la navigation qui, dans le cas de pageswap, est sur le point de se produire ou, dans le cas de pagereveal, vient de se produire.

Pour ce faire, les navigateurs peuvent désormais exposer des objets NavigationActivation qui contiennent des informations sur la navigation de même origine. Cet objet expose le type de navigation utilisé, ainsi que les entrées d'historique de destination actuelle et finale, telles qu'elles se trouvent dans navigation.entries() de l'API Navigation.

Sur une page activée, vous pouvez accéder à cet objet via navigation.activation. Dans l'événement pageswap, vous pouvez y accéder via e.activation.

Consultez cette démo de profils qui utilise les informations NavigationActivation dans les événements pageswap et pagereveal pour définir les valeurs view-transition-name sur les éléments qui doivent participer à la transition de vue.

De cette façon, vous n'avez pas besoin de décorer chaque élément de la liste avec un view-transition-name à l'avance. Au lieu de cela, cela se produit juste à temps à l'aide de JavaScript, uniquement sur les éléments qui en ont besoin.

Le code est le suivant :

// 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';
    }
  }
});

Le code se nettoie également lui-même en supprimant les valeurs view-transition-name après l'exécution de la transition de vue. La page est ainsi prête pour les navigations successives et peut également gérer la traversée de l'historique.

Pour vous aider, utilisez cette fonction utilitaire qui définit temporairement les view-transition-name.

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 = '';
  }
}

Le code précédent peut maintenant être simplifié comme suit :

// 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);
    }
  }
});

Attendre le chargement du contenu avec le blocage du rendu

Dans certains cas, vous pouvez différer le premier rendu d'une page jusqu'à ce qu'un certain élément soit présent dans le nouveau DOM. Cela évite le scintillement et garantit la stabilité de l'état vers lequel vous effectuez l'animation.

Dans le fichier <head>, définissez un ou plusieurs ID d'éléments qui doivent être présents avant le premier rendu de la page, à l'aide de la balise Meta suivante.

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

Cette balise Meta signifie que l'élément doit être présent dans le DOM, et non que le contenu doit être chargé. Par exemple, avec les images, la simple présence de la balise <img> avec le id spécifié dans l'arborescence DOM suffit pour que la condition prenne la valeur "true". Il est possible que l'image soit encore en cours de chargement.

Avant de bloquer le rendu, sachez que le rendu incrémentiel est un aspect fondamental du Web. Soyez donc prudent lorsque vous choisissez de bloquer le rendu. L'impact du blocage du rendu doit être évalué au cas par cas. Par défaut, évitez d'utiliser blocking=render, sauf si vous pouvez mesurer et évaluer activement son impact sur vos utilisateurs en mesurant l'impact sur vos Core Web Vitals.

Afficher les types de transitions dans les transitions de vues entre documents

Les transitions de vue entre documents sont également compatibles avec les types de transitions de vue pour personnaliser les animations et les éléments capturés.

Par exemple, lorsque vous passez à la page suivante ou précédente dans une pagination, vous pouvez utiliser différentes animations selon que vous passez à une page supérieure ou inférieure de la séquence.

Pour définir ces types à l'avance, ajoutez-les dans la règle @@view-transition :

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

Pour définir les types à la volée, utilisez les événements pageswap et pagereveal pour manipuler la valeur 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);
  }
});

Les types ne sont pas automatiquement transférés de l'objet ViewTransition de l'ancienne page vers l'objet ViewTransition de la nouvelle page. Vous devez déterminer le ou les types à utiliser au moins sur la nouvelle page pour que les animations s'exécutent comme prévu.

Pour répondre à ces types, utilisez le sélecteur de pseudo-classe :active-view-transition-type() de la même manière qu'avec les transitions de vue dans le même document.

/* 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;
  }
}

Étant donné que les types ne s'appliquent qu'à une transition de vue active, ils sont automatiquement supprimés lorsqu'une transition de vue se termine. C'est pourquoi les types fonctionnent bien avec des fonctionnalités telles que BFCache.

Démo

Dans la démonstration de pagination suivante, le contenu de la page glisse vers l'avant ou vers l'arrière en fonction du numéro de la page vers laquelle vous naviguez.

Le type de transition à utiliser est déterminé dans les événements pagereveal et pageswap en examinant les URL de destination et de provenance.

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';
  }
};

Commentaires

Les commentaires des développeurs sont toujours les bienvenus. Pour partager vos suggestions et vos questions, signalez un problème au groupe de travail CSS sur GitHub. Ajoutez le préfixe [css-view-transitions] à votre problème. Si vous rencontrez un bug, signalez-le dans Chromium.