Transitions de vue

Astro prend en charge l’adhésion aux transitions de vue par page avec seulement quelques lignes de code. Les transitions de vue mettent à jour le contenu de votre page sans l’actualisation normale de la navigation pleine page du navigateur et offrent des animations transparentes entre les pages.

Astro fournit un composant de routage <ClientRouter /> qui peut être ajouté au <head> d’une page unique pour contrôler les transitions entre les pages lorsque vous naviguez vers une autre page. Il fournit un routeur léger côté client qui intercepte la navigation et vous permet de naviguer entre les pages.

Ajoutez ce composant à un composant .astro réutilisable, tel qu’un en-tête ou une mise en page commune, pour des transitions de page animées sur l’ensemble de votre site (mode SPA).

La prise en charge des transitions de vue par Astro est assurée par la nouvelle API du navigateur View Transitions et comprend également les éléments suivants :

Quelques options d’animation intégrées, telles que fade, slide, et none.
Le support des animations de navigation vers l’avant et vers l’arrière.
La possibilité de personnaliser tous les aspects de l’animation de transition, et de construire vos propres animations.
L’option d’empêcher la navigation côté client pour les liens qui ne sont pas des pages.
Contrôle du comportement de secours pour les navigateurs qui ne prennent pas encore en charge les API de Transition de Vue.
Prise en charge automatique de prefers-reduced-motion.

Ajouter des Transitions de Vue à une page

Optez pour l’utilisation des transitions de vue sur des pages individuelles en important et en ajoutant le composant de routage <ClientRouter /> dans la balise <head> sur chaque page souhaitée.

---
import { ClientRouter } from 'astro:transitions';
---
<html lang="fr">
  <head>
    <title>Ma page d'accueil</title>
    <ClientRouter />
  </head>
  <body>
    <h1>Bienvenue sur mon site web !</h1>
  </body>
</html>

Transitions de vue du site complet (mode SPA)

Importez et ajoutez le composant <ClientRouter /> à votre <head> commun ou au composant de mise en page partagé. Astro créera des animations de page par défaut basées sur les similitudes entre l’ancienne et la nouvelle page, et fournira également un comportement de repli pour les navigateurs non pris en charge.

L’exemple ci-dessous montre l’ajout des animations de navigation par défaut d’Astro sur l’ensemble du site, y compris l’option de contrôle de repli par défaut pour les navigateurs non compatibles, en important et en ajoutant ce composant à un composant <CommonHead /> d’Astro :

---
import { ClientRouter } from 'astro:transitions';
---
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="generator" content={Astro.generator} />

<!-- Balises méta principales -->
<title>{title}</title>
<meta name="title" content={title} />
<meta name="description" content={description} />

<ClientRouter />

Aucune autre configuration n’est nécessaire pour activer la navigation côté client par défaut d’Astro !

Utilisez les directives de transition ou remplacer la navigation par défaut côté client sur des éléments individuels pour un contrôle plus fin.

Directives de transition

Astro attribuera automatiquement aux éléments correspondants trouvés à la fois dans l’ancienne et la nouvelle page un nom unique et partagé view-transition-name. Cette paire d’éléments correspondants est déduite à la fois du type d’élément et de son emplacement dans le DOM.

Utilisez les directives optionnelles transition:* sur les éléments de page dans vos composants .astro pour un contrôle plus fin du comportement de transition de la page pendant la navigation.

transition:name : Permet d’outrepasser la correspondance d’éléments par défaut d’Astro pour l’animation du contenu ancien/nouveau et de spécifier un nom de transition pour associer une paire d’éléments DOM.
transition:animate : Permet d’outrepasser l’animation par défaut d’Astro tout en remplaçant l’ancien élément par le nouveau en spécifiant un type d’animation. Utilisez les directives d’animation intégrées ou créer des animations de transition personnalisées Astro.
transition:persist : Permet d’outrepasser le remplacement par défaut des anciens éléments par de nouveaux et de conserver les composants et les éléments HTML lorsque l’on navigue vers une autre page.

Nommer une transition

Dans certains cas, vous pouvez vouloir ou devoir identifier vous-même les éléments de transition de vue correspondants. Vous pouvez spécifier un nom pour une paire d’éléments en utilisant la directive transition:name.

<aside transition:name="hero">

<aside transition:name="hero">

Notez que la valeur transition:name fournie ne peut être utilisée qu’une seule fois par page. Définissez cette valeur manuellement lorsque Astro ne peut pas déduire lui-même un nom approprié, ou pour un contrôle plus fin des éléments correspondants.

Maintenir l’état

Ajouté à la version : astro@2.10.0

Vous pouvez faire persister les composants et les éléments HTML (au lieu de les remplacer) à travers les pages naviguées en utilisant la directive transition:persist.

Par exemple, l’élément <video> suivant continuera à être joué lorsque vous naviguerez au sein d’une autre page contenant le même élément vidéo. Cela fonctionne aussi bien pour la navigation vers l’avant que vers l’arrière.

<video controls="" autoplay="" transition:persist>
  <source src="https://ia804502.us.archive.org/33/items/GoldenGa1939_3/GoldenGa1939_3_512kb.mp4" type="video/mp4">
</video>

Vous pouvez également placer la directive sur une île Astro (un Framework UI avec une directive client:). Si ce composant existe sur la page suivante, l’île de l’ancienne page avec son état actuel continuera d’être affichée, au lieu d’être remplacée par l’île de la nouvelle page.

Dans l’exemple ci-dessous, l’état interne du compteur du composant ne sera pas réinitialisé lors de la navigation entre les pages qui contiennent le composant <Counter /> avec l’attribut transition:persist.

<Counter client:load transition:persist initialCount={5} />

Vous pouvez également identifier manuellement les éléments correspondants si l’île/l’élément se trouve dans un composant différent entre les deux pages.

<Video controls="" autoplay="" transition:name="media-player" transition:persist />

<MyVideo controls="" autoplay="" transition:name="media-player" transition:persist />

Comme raccourci pratique, transition:persist peut aussi prendre un nom de transition comme valeur.

<video controls="" autoplay="" transition:persist="media-player">

`transition:persist-props`

Ajouté à la version : astro@4.5.0

Cela vous permet de contrôler si les props d’une île doivent ou non être conservées lors de la navigation.

Par défaut, lorsque vous ajoutez transition:persist à une île, l’état est conservé lors de la navigation, mais votre composant sera re-rendu avec de nouvelles props. Ceci est utile, par exemple, lorsqu’un composant reçoit des props spécifiques à une page, comme le title de la page courante.

Vous pouvez modifier ce comportement en définissant transition:persist-props en plus de transition:persist. L’ajout de cette directive conservera les props existantes d’une île (sans les rendre avec de nouvelles valeurs) en plus de maintenir son état existant.

Directives d’animation intégrées

Astro est livré avec quelques animations intégrées pour remplacer la transition par défaut fade. Ajoutez la directive transition:animate à des éléments individuels pour personnaliser le comportement de transitions spécifiques.

fade (par défaut) : Une animation de fondu enchaîné. L’ancien contenu disparaît et le nouveau contenu apparaît en fondu.
initial : Permet de ne pas utiliser l’animation de fondu enchaîné d’Astro et d’utiliser le style par défaut du navigateur.
slide : Une animation où l’ancien contenu glisse vers la gauche et le nouveau contenu glisse vers la droite. En navigation arrière, les animations sont inversées.
none : Désactive les animations par défaut du navigateur. À utiliser sur l’élément <html> d’une page pour désactiver le fondu par défaut pour tous les éléments de la page.

Combinez les directives pour un contrôle total de l’animation de votre page. Définissez une page par défaut sur l’élément <html>, et modifiez les éléments individuels comme vous le souhaitez.

L’exemple ci-dessous produit une animation de diapositive pour le corps du texte tout en désactivant l’animation de fondu par défaut du navigateur pour le reste de la page :

---
import CommonHead from '../components/CommonHead.astro';
---

<html transition:name="root" transition:animate="none">
  <head>
    <CommonHead />
  </head>
  <body>
    <header>
      ...
    </header>
    <!-- Remplace la valeur par défaut de votre page par un seul élément -->
    <main transition:animate="slide">
      ...
    </main>
  </body>
</html>

Personnalisation des animations

Vous pouvez personnaliser tous les aspects d’une transition avec n’importe quelle propriété d’animation CSS.

Pour personnaliser une animation intégrée, il faut d’abord importer l’animation depuis astro:transitions, puis passer les options de personnalisation.

L’exemple ci-dessous personnalise la durée de l’animation intégrée fade :

---
import { fade } from 'astro:transitions';
---

<header transition:animate={fade({ duration: '0.4s' })}>

Vous pouvez également définir vos propres animations à utiliser avec transition:animate en définissant le comportement en avant et en arrière, ainsi que les nouvelles et les anciennes pages, selon les types suivants :

export interface TransitionAnimation {
  name: string; // Nom de l'image clé
  delay?: number | string;
  duration?: number | string;
  easing?: string;
  fillMode?: string;
  direction?: string;
}

export interface TransitionAnimationPair {
  old: TransitionAnimation | TransitionAnimation[];
  new: TransitionAnimation | TransitionAnimation[];
}

export interface TransitionDirectionalAnimations {
  forwards: TransitionAnimationPair;
  backwards: TransitionAnimationPair;
}

L’exemple suivant montre toutes les propriétés nécessaires pour définir une animation bump personnalisée à l’intérieur d’une balise <style is:global> dans votre fichier de mise en page racine :

---
import { ClientRouter } from 'astro:transitions';
---

<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
  </body>
</html>

<style is:global>
  @keyframes bump {
    0% {
      opacity: 0;
      transform: scale(1) translateX(200px);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.1);
    }
    100% {
      opacity: 1;
      transform: scale(1) translateX(0);
    }
  }
</style>

Le comportement de l’animation doit être défini dans le frontmatter de chaque composant utilisant l’animation :

---
const anim = {
  old: {
    name: 'bump',
    duration: '0.5s',
    easing: 'ease-in',
    direction: 'reverse',
  },
  new: {
    name: 'bump',
    duration: '0.5s',
    easing: 'ease-in-out',
  },
};

const customTransition = {
  forwards: anim,
  backwards: anim,
};
---

<header transition:animate={customTransition}> ... </header>

Vous disposez d’une grande flexibilité pour définir des animations personnalisées. Pour obtenir le résultat souhaité, vous pouvez envisager des combinaisons inhabituelles, telles qu’utiliser des objets différents pour les propriétés forwards et backwards, ou fournir des étapes d’animations distinctes pour les propriétés old et new.

Contrôle du routeur

Le routeur <ClientRouter /> gère la navigation en observant :

les clics sur les éléments <a>.
les événements de navigation vers l’avant et vers l’arrière.

Les options suivantes vous permettent de contrôler davantage le moment où la navigation s’effectue dans le routeur :

data-astro-reload : un attribut de balise <a> pour forcer une navigation pleine page
data-astro-history="auto | push | replace" : un attribut de balise <a> pour contrôler l’historique du navigateur
navigate(href, options) : une méthode disponible pour n’importe quel script ou composant client pour déclencher la navigation

Dans certains cas, il n’est pas possible de naviguer via le routage côté client, car les deux pages concernées doivent utiliser le routeur <ClientRouter /> pour éviter un rechargement complet de la page. Il se peut également que vous ne souhaitiez pas un routage côté client à chaque changement de navigation et que vous préfériez une navigation de page traditionnelle sur des itinéraires sélectionnés.

Vous pouvez renoncer au routage côté client pour chaque lien en ajoutant l’attribut data-astro-reload à n’importe quelle balise <a> ou <form>. Cet attribut remplacera tout composant <ClientRouter /> existant et déclenchera à la place un rafraîchissement du navigateur pendant la navigation.

L’exemple suivant montre que l’on empêche le routage côté client lorsque l’on navigue au sein d’un article à partir de la page d’accueil uniquement. Cela permet néanmoins d’animer des éléments partagés, tels qu’une image de héros, lorsque l’on navigue vers la même page à partir d’une page de liste d’articles :

<a href="/articles/emperor-penguins" data-astro-reload>

<a href="/articles/emperor-penguins">

Les liens avec l’attribut data-astro-reload seront ignorés par le routeur et une navigation pleine page se produira.

Vous pouvez aussi déclencher la navigation côté client via des événements qui ne sont pas normalement écoutés par le routeur <ClientRouter /> en utilisant navigate. Cette fonction du module astro:transitions/client peut être utilisée dans les scripts et dans les composants du framework qui sont hydratés avec une directive client.

L’exemple suivant montre un composant Astro qui permet à un visiteur de naviguer vers une autre page qu’il sélectionne dans un menu :

<script>
  import { navigate } from 'astro:transitions/client';

  // Naviguer automatiquement vers l'option sélectionnée.
  document.querySelector('select').onchange = (ev) => {
      let href = ev.target.value;
      navigate(href);
  };
</script>
<select>
  <option value="/play">Jouer</option>
  <option value="/blog">Blog</option>
  <option value="/about">A propos</option>
  <option value="/contact">Contact</option>
</select>

---
import Form from "../components/Form.astro";
import { ClientRouter } from "astro:transitions";
---
<html>
  <head>
    <ClientRouter />
  </head>
  <body>
    <Form />
  </body>
</html>

L’exemple suivant met en œuvre la même chose en utilisant navigate() dans un composant React <Form /> :

import { navigate } from 'astro:transitions/client';

export default function Form() {
  return (
    <select onChange={(e) => navigate(e.target.value)}>
      <option value="/play">Jouer</option>
      <option value="/blog">Blog</option>
      <option value="/about">A propos</option>
      <option value="/contact">Contact</option>
    </select>
  );
}

Le composant <Form /> peut alors être rendu sur une page Astro qui utilise le routeur <ClientRouter />, avec une directive client :

---
import Form from "../components/form.jsx";
import { ClientRouter } from "astro:transitions";
---
<html>
  <head>
    <ClientRouter />
  </head>
  <body>
    <Form client:load />
  </body>
</html>

La méthode navigate prend ces arguments :

href (obligatoire) - La nouvelle page vers laquelle naviguer.
options - Un objet optionnel avec les propriétés suivantes :
history : 'push' | 'replace' | 'auto'
'push' : le routeur utilisera history.pushState pour créer une nouvelle entrée dans l’historique du navigateur.
'replace' : le routeur utilisera history.replaceState pour mettre à jour l’URL sans ajouter une nouvelle entrée dans la navigation.
'auto' (par défaut) : le routeur va essayer history.pushState, mais si l’URL n’est pas une URL vers laquelle il est possible d’effectuer une transition, l’URL actuelle sera conservée sans modification de l’historique du navigateur.
formData : Un objet FormData pour les requêtes POST.

Pour la navigation vers l’arrière et vers l’avant dans l’historique du navigateur, vous pouvez combiner navigate() avec les fonctions intégrées history.back(), history.forward() et history.go() du navigateur. Si navigate() est appelé pendant le rendu côté serveur de votre composant, il n’a aucun effet.

Remplacer les entrées dans l’historique du navigateur

Normalement, chaque fois que vous naviguez, une nouvelle entrée est inscrite dans l’historique du navigateur. Cela permet de naviguer entre les pages à l’aide des boutons “retour” et “avant” du navigateur.

Le routeur <ClientRouter /> vous permet d’écraser les entrées de l’historique en ajoutant l’attribut data-astro-history à n’importe quelle balise <a>.

L’attribut data-astro-history peut être défini avec les trois mêmes valeurs que l’option history de la fonction navigate() :

data-astro-history : 'push' | 'replace' | 'auto'

'push' : le routeur utilisera history.pushState pour créer une nouvelle entrée dans l’historique du navigateur.
'replace' : le routeur utilisera history.replaceState pour mettre à jour l’URL sans ajouter une nouvelle entrée dans la navigation.
'auto' (par défaut) : le routeur tentera history.pushState, mais si l’URL n’est pas une URL vers laquelle il est possible d’effectuer une transition, l’URL actuelle sera conservée sans modification de l’historique du navigateur.

L’exemple suivant navigue vers la page /main mais n’ajoute pas une nouvelle entrée à l’historique de navigation. Au lieu de cela, il réutilise l’entrée actuelle dans l’historique (/confirmation) et l’écrase.

<a href="/main" data-astro-history="replace">

Cela a pour effet que si vous revenez en arrière à partir de la page /main, le navigateur n’affichera pas la page /confirmation, mais la page qui la précède.

Transitions avec les formulaires

Ajouté à la version : astro@4.0.0

Le routeur <ClientRouter /> déclenche des transitions dans la page à partir d’éléments <form>, supportant à la fois les requêtes GET et POST.

Par défaut, Astro soumet les données de votre formulaire en tant que multipart/form-data lorsque votre method est réglé sur POST. Si vous voulez correspondre au comportement par défaut des navigateurs web, utilisez l’attribut enctype pour soumettre vos données encodées en tant que application/x-www-form-urlencoded :

<form action="/contact" method="POST" enctype="application/x-www-form-urlencoded">
  <!-- -->
</form>

Vous pouvez refuser les transitions de routeur sur un formulaire individuel en utilisant l’attribut data-astro-reload :

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

Gestion de solution de secours

Le routeur <ClientRouter /> fonctionne mieux dans les navigateurs qui supportent les Transitions de Vues (c’est-à-dire les navigateurs Chromium), mais il inclut également un support de secours par défaut pour les autres navigateurs. Même si le navigateur ne prend pas en charge l’API View Transitions, Astro fournira toujours une navigation dans le navigateur en utilisant l’une des options de secours pour une expérience comparable.

Vous pouvez surcharger le support par défaut d’Astro en ajoutant une propriété fallback sur le composant <ClientRouter /> et en la réglant sur swap ou none :

animate (par défaut, recommandé) - Astro simulera des transitions de vues en utilisant des attributs personnalisés avant de mettre à jour le contenu de la page.
swap - Astro n’essaiera pas d’animer la page. Au lieu de cela, l’ancienne page sera immédiatement remplacée par la nouvelle.
none - Astro n’effectuera aucune transition de page animée. Au lieu de cela, vous obtiendrez une navigation pleine page dans les navigateurs qui ne la supportent pas.

---
import { ClientRouter } from 'astro:transitions';
---
<title>Mon site</title>

<ClientRouter fallback="swap" />

Lors de l’utilisation du routeur <ClientRouter />, les étapes suivantes se produisent pour produire la navigation côté client d’Astro :

Un visiteur de votre site déclenche la navigation par l’une des actions suivantes :
- Cliquer sur une balise <a> qui renvoie à une autre page de votre site.
- Cliquer sur le bouton “Précédent”.
- Cliquer sur le bouton “Avancer”.
Le routeur commence à chercher la page suivante.
Le routeur ajoute l’attribut data-astro-transition à l’élément HTML avec la valeur 'forward' ou 'back' selon le cas.
Le routeur appelle document.startViewTransition. Cela déclenche le processus de Transition de Vue du navigateur. Il est important de noter que le navigateur fait une capture d’écran de l’état actuel de la page.
Dans le callback startViewTransition, le routeur effectue un swap, qui consiste en la séquence d’événements suivante :
- Le contenu du <head> est remplacé, certains éléments étant conservés :
- Les nœuds DOM des feuilles de style sont conservés s’ils existent sur la nouvelle page, afin d’éviter les FOUC.
- Les scripts sont conservés s’ils existent sur la nouvelle page.
- Tous les autres éléments d’en-tête avec transition:persist sont conservés s’il existe un élément correspondant dans la nouvelle page.
- Le <body> est complètement remplacé par le corps de la nouvelle page.
- Les éléments marqués transition:persist sont déplacés vers le nouveau DOM s’ils existent sur la nouvelle page.
- La position de défilement est restaurée si nécessaire.
- L’événement astro:after-swap est déclenché sur le document. C’est la fin du processus de swap.
Le routeur attend le chargement de toute nouvelle feuille de style avant de résoudre la transition.
Le routeur exécute tous les nouveaux scripts ajoutés à la page.
L’événement astro:page-load se déclenche. C’est la fin du processus de navigation.

Comportement du script avec les transitions de vue

Lorsque vous ajoutez des transitions de vue à un projet Astro existant, il se peut que certains de vos scripts ne s’exécutent plus après la navigation dans la page, comme c’était le cas lors de l’actualisation complète du navigateur. Utilisez les informations suivantes pour vous assurer que vos scripts s’exécutent comme prévu.

Ordre de script

Lorsque l’on navigue entre les pages avec le composant <ClientRouter />, les scripts sont exécutés dans un ordre séquentiel pour correspondre au comportement du navigateur.

Réexécution du script

Les scripts des modules intégrés, qui sont les scripts par défaut dans Astro, ne sont exécutés qu’une seule fois. Après l’exécution initiale, ils seront ignorés, même si le script existe sur la nouvelle page après une transition.

Contrairement aux scripts de modules intégrés, les scripts inline peuvent être réexécutés au cours de la visite d’un utilisateur sur un site s’ils se trouvent sur une page visitée plusieurs fois. Les scripts en ligne peuvent également être réexécutés lorsqu’un visiteur navigue vers une page sans script, puis de nouveau vers une page avec le script.

Avec les transitions de vue, certains scripts peuvent ne plus être réexécutés après la navigation vers une nouvelle page comme c’est le cas avec les actualisations complètes du navigateur. Il existe plusieurs événements pendant le routage côté client que vous pouvez écouter et déclencher des événements lorsqu’ils se produisent. Vous pouvez encapsuler un script existant dans un écouteur d’événements pour garantir qu’il s’exécute au bon moment dans le cycle de navigation.

L’exemple suivant encapsule un script pour un menu mobile « hamburger » dans un écouteur d’événement pour astro:page-load qui s’exécute à la fin de la navigation dans la page pour rendre le menu réactif lorsqu’on clique dessus après la navigation vers une nouvelle page :

<script>
document.addEventListener('astro:page-load', () => {
  document.querySelector('.hamburger').addEventListener('click', () => {
    document.querySelector('.nav-links').classList.toggle('expanded');
  });
});
</script>

L’exemple suivant montre une fonction qui s’exécute en réponse à l’événement astro:after-swap, qui se produit immédiatement après que la nouvelle page a remplacé l’ancienne page et avant que les éléments DOM ne soient affichés à l’écran. Cela permet d’éviter un flash de thème clair après la navigation dans la page en vérifiant et, si nécessaire, en définissant le thème en mode sombre avant le rendu de la nouvelle page :

<script is:inline>
  function applyTheme() {
    localStorage.theme === 'dark'
      ? document.documentElement.classList.add("dark")
      : document.documentElement.classList.remove("dark");
  }

  document.addEventListener('astro:after-swap', applyTheme);
  applyTheme();
</script>

`data-astro-rerun`

Ajouté à la version : astro@4.5.0

Pour forcer les scripts inline à se réexécuter après chaque transition, ajoutez la propriété data-astro-rerun. L’ajout de n’importe quel attribut à un script ajoute aussi implicitement is:inline, donc ceci n’est disponible que pour les scripts qui ne sont pas regroupés et traités par Astro.

<script is:inline data-astro-rerun>...</script>

Pour s’assurer qu’un script s’exécute à chaque fois qu’une page est chargée pendant la navigation côté client, il doit être exécuté par un lifecycle event. Par exemple, les récepteurs d’événements pour DOMContentLoaded peuvent être remplacés par l’événement de cycle de vie astro:page-load.

Si vous avez du code qui établit un état global dans un script en ligne, cet état devra prendre en compte le fait que le script peut s’exécuter plus d’une fois. Vérifiez l’état global dans votre balise <script>, et exécutez votre code de manière conditionnelle lorsque c’est possible. Cela fonctionne parce que window est préservé.

<script is:inline>
  if (!window.SomeGlobal) {
    window.SomeGlobal = {} // ....
  }
</script>

Événements du cycle de vie

Le routeur <ClientRouter /> déclenche un certain nombre d’événements sur le document pendant la navigation. Ces événements fournissent des crochets dans le cycle de vie de la navigation, vous permettant de faire des choses comme montrer des indicateurs qu’une nouvelle page est en train de se charger, surcharger le comportement par défaut, et restaurer l’état lorsque la navigation se termine.

Le processus de navigation comprend une phase de préparation, au cours de laquelle le nouveau contenu est chargé ; une phase d’échange de DOM, au cours de laquelle le contenu de l’ancienne page est remplacé par celui de la nouvelle ; et une phase d’achèvement, au cours de laquelle les scripts sont exécutés, le chargement est signalé comme étant terminé et le travail de nettoyage est effectué.

Les événements du cycle de vie de l’API de transition de vue d’Astro sont, dans l’ordre, les suivants :

astro:before-preparation
astro:after-preparation
astro:before-swap
astro:after-swap
astro:page-load

Si certaines actions peuvent être déclenchées lors de n’importe quel événement, d’autres tâches ne peuvent être exécutées que lors d’un événement spécifique pour obtenir les meilleurs résultats, comme l’affichage d’une barre de chargement avant la préparation ou la modification des paires d’animations avant le changement de contenu.

`astro:before-preparation`

Ajouté à la version : astro@3.6.0

Un événement qui se déclenche au début de la phase de préparation, après que la navigation a commencé (par exemple, après que l’utilisateur a cliqué sur un lien), mais avant que le contenu ne soit chargé.

Cet événement est utilisé :

pour faire quelque chose avant que le chargement n’ait commencé, par exemple afficher un indicateur de chargement
Pour modifier le chargement, comme charger le contenu que vous avez défini dans un modèle plutôt qu’à partir de l’URL externe.
Pour changer la direction de la navigation (qui est généralement soit forward soit backward) pour une animation personnalisée.

Voici un exemple d’utilisation de l’événement astro:before-preparation pour charger un spinner avant le chargement du contenu et l’arrêter immédiatement après le chargement. Notez que l’utilisation du callback du chargeur de cette manière permet l’exécution asynchrone du code.

<script is:inline>
  document.addEventListener('astro:before-preparation', ev => {
    const originalLoader = ev.loader;
    ev.loader = async function() {
      const { startSpinner } = await import('./spinner.js');
      const stop = startSpinner();
      await originalLoader();
      stop();
    };
  });
</script>

`astro:after-preparation`

Ajouté à la version : astro@3.6.0

Événement qui se déclenche à la fin de la phase de préparation, après que le contenu de la nouvelle page a été chargé et analysé dans un document. Cet événement se produit avant la phase de transition des vues.

Cet exemple utilise l’événement astro:before-preparation pour démarrer un indicateur de chargement et l’événement astro:after-preparation pour l’arrêter :

<script is:inline>
  document.addEventListener('astro:before-preparation', () => {
    document.querySelector('#loading').classList.add('show');
  });
  document.addEventListener('astro:after-preparation', () => {
    document.querySelector('#loading').classList.remove('show');
  });
</script>

Il s’agit d’une version plus simple du chargement d’un spinner que l’exemple ci-dessus : si tout le code de l’auditeur peut être exécuté de manière synchrone, il n’est pas nécessaire de s’accrocher au callback du chargeur.

`astro:before-swap`

Ajouté à la version : astro@3.6.0

Événement qui se déclenche avant que le nouveau document (qui est rempli pendant la phase de préparation) ne remplace le document actuel. Cet événement se produit à l’intérieur de la transition de vue, où l’utilisateur voit encore un instantané de l’ancienne page.

Cet événement peut être utilisé pour effectuer des modifications avant que la permutation ne se produise. La propriété newDocument de l’événement représente le document entrant. Voici un exemple permettant de s’assurer que les préférences du navigateur en matière de mode clair ou foncé dans localStorage sont reportées sur la nouvelle page :

<script is:inline>
  function setDarkMode(document) {
    let theme = localStorage.darkMode ? 'dark' : 'light';
    document.documentElement.dataset.theme = theme;
  }

  setDarkMode(document);

  document.addEventListener('astro:before-swap', ev => {
    // Transmettre le document entrant pour définir le thème sur celui-ci
    setDarkMode(ev.newDocument);
  });
</script>

L’événement astro:before-swap peut aussi être utilisé pour changer l’implémentation de la permutation. L’implémentation par défaut de la permutation diffère le contenu de l’en-tête, déplace les éléments persistants de l’ancien document vers newDocument, et remplace ensuite le body entier par le corps du nouveau document.

À ce stade du cycle de vie, vous pouvez choisir de définir votre propre implémentation de l’échange, par exemple pour diffuser l’intégralité du contenu du document existant (ce que font certains autres routeurs) :

<script is:inline>
  document.addEventListener('astro:before-swap', ev => {
    ev.swap = () => {
      diff(document, ev.newDocument);
    };
  });
</script>

Créer une fonction d’échange personnalisée

Ajouté à la version : astro@4.15.0

L’objet swapFunctions du module astro:transitions/client fournit cinq fonctions utilitaires qui gèrent des tâches spécifiques liées à l’échange, notamment la gestion des attributs de document, des éléments de page et l’exécution de scripts. Ces fonctions peuvent être utilisées directement pour définir une implémentation d’échange personnalisée.

L’exemple suivant montre comment utiliser ces fonctions pour recréer l’implémentation d’échange intégrée d’Astro :

<script>
import { swapFunctions } from 'astro:transitions/client';

// remplace window.document par doc
function mySwap(doc: Document) {
  swapFunctions.deselectScripts(doc);
  swapFunctions.swapRootAttributes(doc);
  swapFunctions.swapHeadElements(doc);
  const restoreFocusFunction = swapFunctions.saveFocus();
  swapFunctions.swapBodyElement(doc.body, document.body);
  restoreFocusFunction();
};

...
  event.swap = () => mySwap(event.newDocument);
...
<script>

Les implémentations d’échange personnalisées peuvent commencer avec ce modèle et ajouter ou remplacer des étapes individuelles par une logique personnalisée selon les besoins.

`astro:after-swap`

Un événement qui se déclenche immédiatement après que la nouvelle page ait remplacé l’ancienne. Vous pouvez écouter cet événement sur document et déclencher des actions qui se produiront avant le rendu des éléments DOM de la nouvelle page et l’exécution des scripts.

Cet événement, lorsqu’il est écouté sur la page sortante, est utile pour transmettre et restaurer tout état du DOM qui doit être transféré sur la nouvelle page.

Il s’agit du dernier point du cycle de vie où il est encore possible, par exemple, d’ajouter un nom de classe en mode sombre (<html class="dark-mode">), bien que vous puissiez souhaiter le faire dans un événement antérieur.

L’événement astro:after-swap se produit immédiatement après la mise à jour de l’historique du navigateur et la définition de la position de défilement. Par conséquent, l’une des utilisations du ciblage de cet événement consiste à remplacer la restauration du défilement par défaut pour la navigation dans l’historique. L’exemple suivant réinitialise la position de défilement horizontale et verticale au coin supérieur gauche de la page pour chaque navigation.

document.addEventListener('astro:after-swap',
  () => window.scrollTo({ left: 0, top: 0, behavior: 'instant' }))

`astro:page-load`

Un événement qui se déclenche à la fin de la navigation de la page, après que la nouvelle page soit visible par l’utilisateur et que les styles et les scripts bloquants soient chargés. Vous pouvez écouter cet événement sur le document.

Le composant <ClientRouter /> déclenche cet événement à la fois lors de la navigation initiale sur une page pré-rendue et lors de toute navigation ultérieure, que ce soit en avant ou en arrière.

Vous pouvez utiliser cet événement pour exécuter du code à chaque navigation de page, par exemple pour configurer des écouteurs d’événements qui autrement seraient perdus pendant la navigation.

<script>
  document.addEventListener('astro:page-load', () => {
    // Cette opération s'exécute lors du premier chargement de la page et après chaque navigation.
    setupStuff(); // par exemple, ajouter des écouteurs d'événements
  });
</script>

Accessibilité

L’activation du routage côté client et l’animation des transitions de page posent toutes deux des problèmes d’accessibilité, et Astro vise à rendre les sites qui optent pour View Transitions aussi accessibles par défaut que possible.

Annonce de la route

Ajouté à la version : astro@3.2.0

Le composant <ClientRouter /> inclut un annonceur de route pour la navigation de page pendant le routage côté client. Aucune configuration ou action n’est nécessaire pour l’activer.

Les technologies d’assistance permettent aux visiteurs de savoir que la page a changé en annonçant le nouveau titre de la page après la navigation. Lors de l’utilisation du routage côté serveur avec un rafraîchissement traditionnel de la page entière du navigateur, cela se produit par défaut après le chargement de la nouvelle page. Dans le cas du routage côté client, c’est le composant <ClientRouter /> qui effectue cette action.

Pour ajouter l’annonce d’itinéraire au routage côté client, le composant ajoute un élément à la nouvelle page avec l’attribut aria-live fixé à assertive. Cela indique à AT (technologie d’assistance) d’annoncer immédiatement. Le composant vérifie également les éléments suivants, par ordre de priorité, pour déterminer le texte de l’annonce :

Le <title>, s’il existe.
Le premier <h1> qu’il trouve.
Le pathname de la page.

Nous vous recommandons vivement de toujours inclure un <title> dans chaque page pour des raisons d’accessibilité.

`prefers-reduced-motion`

Le composant <ClientRouter /> d’Astro inclut une requête média CSS qui désactive toutes les animations de transition de vue, y compris l’animation de secours, lorsque le paramètre prefer-reduced-motion est détecté. À la place, le navigateur échangera simplement les éléments DOM sans animation.

Contribuer

Communauté

Transitions de vue

Ajouter des Transitions de Vue à une page

Transitions de vue du site complet (mode SPA)

Directives de transition

Nommer une transition

Maintenir l’état

`transition:persist-props`

Directives d’animation intégrées

Personnalisation des animations

Contrôle du routeur

Empêcher la navigation côté client

Déclenchement de la navigation

Remplacer les entrées dans l’historique du navigateur

Transitions avec les formulaires

Gestion de solution de secours

Processus de navigation du côté client

Comportement du script avec les transitions de vue

Ordre de script

Réexécution du script

`data-astro-rerun`

Événements du cycle de vie

`astro:before-preparation`

`astro:after-preparation`

`astro:before-swap`

Créer une fonction d’échange personnalisée

`astro:after-swap`

`astro:page-load`

Accessibilité

Annonce de la route

`prefers-reduced-motion`

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Envoyez-nous un commentaire

Envoyez-nous un commentaire