Référence de l'API de transitions de vue

Ajouté à la version : astro@3.0.0

Ce module fournit des fonctions pour contrôler et interagir avec l’API Transitions de Vue et le routeur côté client.

Pour des fonctionnalités et des exemples d’utilisation, consultez notre guide sur les Transitions de Vue.

Importations depuis `astro:transitions`

import { ViewTransitions, fade, slide } from 'astro:transitions';

`<ViewTransitions />`

Ajouté à la version : astro@3.0.0

Choisissez d’utiliser les transitions de vue sur des pages individuelles en important et en ajoutant le composant de routage <ViewTransitions /> dans la balise <head> sur chaque page souhaitée.

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

Découvrez comment contrôler le routeur et ajouter des directives de transition aux éléments et composants de la page.

`fade`

Type : (opts: { duration?: string | number }) => TransitionDirectionalAnimations

Ajouté à la version : astro@3.0.0

Fonction utilitaire permettant de prendre en charge la personnalisation de la durée de l’animation fade intégrée.

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

<!-- Transition en fondu avec la durée par défaut -->
<div transition:animate="fade" />

<!-- Transition en fondu d'une durée de 400 millisecondes -->
<div transition:animate={fade({ duration: '0.4s' })} />

`slide`

Type : (opts: { duration?: string | number }) => TransitionDirectionalAnimations

Ajouté à la version : astro@3.0.0

Fonction utilitaire permettant de prendre en charge la personnalisation de la durée de l’animation slide intégrée.

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

<!-- Transition de glissement avec la durée par défaut -->
<div transition:animate="slide" />

<!-- Transition de glissement d'une durée de 400 millisecondes -->
<div transition:animate={slide({ duration: '0.4s' })} />

Importations depuis `astro:transitions/client`

<script>
  import {
    navigate,
    supportsViewTransitions,
    transitionEnabledOnThisPage,
    getFallback,
    swapFunctions,
  } from 'astro:transitions/client';
</script>

`navigate()`

Type : (href: string, options?: Options) => void

Ajouté à la version : astro@3.2.0

Une fonction qui exécute une navigation vers le href donné à l’aide de l’API Transitions de Vue.

Cette signature de fonction est basée sur la fonction navigate de l’API Navigation du navigateur. Bien que basée sur l’API Navigation, cette fonction est implémentée sur l’API History pour permettre la navigation sans recharger la page.

Option `history`

Type : 'auto' | 'push' | 'replace'
Par défaut : 'auto'

Ajouté à la version : astro@3.2.0

Définit la manière dont cette navigation doit être ajoutée à l’historique du navigateur.

'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 de nouvelle entrée dans la navigation.
'auto' (par défaut) : le routeur tentera history.pushState, mais si l’URL ne peut pas être transférée, l’URL actuelle restera sans modification de l’historique du navigateur.

Cette option suit l’option history de l’API Navigation du navigateur mais simplifiée pour les cas qui peuvent survenir sur un projet Astro.

Option `formData`

Type : FormData

Ajouté à la version : astro@3.5.0

Un objet FormData pour les requêtes POST.

Lorsque cette option est transmise, les requêtes vers la page cible de navigation seront envoyées sous forme de requête POST avec l’objet de données du formulaire comme contenu.

L’envoi d’un formulaire HTML avec les transitions de vue activées utilisera cette méthode au lieu de la navigation par défaut avec rechargement de page. L’appel de cette méthode permet de déclencher le même comportement par programmation.

Option `info`

Type : any

Ajouté à la version : astro@3.6.0

Données arbitraires à inclure dans les événements astro:before-preparation et astro:before-swap provoqués par cette navigation.

Cette option imite l’option info de l’API Navigation du navigateur.

Option `state`

Type : any

Ajouté à la version : astro@3.6.0

Données arbitraires à associer à l’objet NavitationHistoryEntry créé par cette navigation. Ces données peuvent ensuite être récupérées à l’aide de la fonction history.getState de l’API History.

Cette option imite l’option state de l’API Navigation du navigateur.

Option `sourceElement`

Type : Element

Ajouté à la version : astro@3.6.0

L’élément qui a déclenché cette navigation, le cas échéant. Cet élément sera disponible dans les événements suivants :

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

Type : boolean

Ajouté à la version : astro@3.2.0

Indique si les transitions de vue sont prises en charge et activées dans le navigateur actuel.

`transitionEnabledOnThisPage`

Type : boolean

Ajouté à la version : astro@3.2.0

Indique si la page actuelle comporte ou non des transitions d’affichage activées pour la navigation côté client. Cela peut être utilisé pour créer des composants qui se comportent différemment lorsqu’ils sont utilisés sur des pages avec des transitions de vue.

`getFallback()`

Type : () => 'none' | 'animate' | 'swap'

Ajouté à la version : astro@3.6.0

Renvoie la stratégie de secours à utiliser dans les navigateurs qui ne prennent pas en charge les transitions de vue.

Voir le guide sur la Gestion de solution de secours pour savoir comment choisir et configurer le comportement de repli.

`swapFunctions`

Ajouté à la version : astro@4.15.0

Un objet contenant les fonctions utilitaires utilisées pour créer la fonction d’échange par défaut d’Astro. Celles-ci peuvent être utiles lors de la création d’une fonction d’échange personnalisée.

swapFunctions fournit les méthodes suivantes :

`deselectScripts()`

Type : (newDocument: Document) => void

Marque les scripts du nouveau document qui ne doivent pas être exécutés. Ces scripts sont déjà présents dans le document actuel et ne sont pas signalés pour une réexécution à l’aide de data-astro-rerun.

`swapRootAttributes()`

Type : (newDocument: Document) => void

Échange les attributs entre les racines du document, comme l’attribut lang. Cela inclut également les attributs internes injectés par Astro comme data-astro-transition, qui rendent la direction de transition disponible pour les règles CSS générées par Astro.

Lors de la création d’une fonction d’échange personnalisée, il est important d’appeler cette fonction afin de ne pas interrompre les animations de transition de vue.

`swapHeadElements()`

Type : (newDocument: Document) => void

Supprime tous les éléments présents dans la balise <head> du document actuel qui ne sont pas conservés dans le nouveau document. Ajoute ensuite tous les nouveaux éléments présents dans la balise <head> du nouveau document dans celle du document courant.

`saveFocus()`

Type : () => () => void

Stocke l’élément focalisé sur la page actuelle et renvoie une fonction qui, lorsqu’elle est appelée, si l’élément focalisé a été conservé, renvoie le focus sur celui-ci.

`swapBodyElement()`

Type : (newBody: Element, oldBody: Element) => void

Remplace l’ancien corps par le nouveau. Ensuite, il passe en revue chaque élément de l’ancien corps qui doit être conservé et qui possède un élément correspondant dans le nouveau corps avant de remplacer l’ancien élément en place.

Événements du cycle de vie

Événement `astro:before-preparation`

Un événement déclenché au début d’une navigation à l’aide de Transitions de Vue. Cet événement se produit avant toute demande et tout changement d’état du navigateur.

Cet événement possède les attributs suivants :

info
sourceElement
navigationType
direction
from
to
formData
loader

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:after-preparation`

Un événement envoyé après le chargement de la page suivante dans une navigation utilisant des Transitions de Vue.

Cet événement n’a aucun attribut.

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:before-swap`

Un événement envoyé après que la page suivante est analysée, préparée et liée à un document en prévision de la transition, mais avant que tout contenu ne soit échangé entre les documents.

Cet événement ne peut pas être annulé. L’appel de preventDefault() est une opération interdite.

Cet événement possède les attributs suivants :

info
sourceElement
navigationType
direction
from
to
viewTransition
swap

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:after-swap`

Un événement envoyé après que le contenu de la page a été échangé mais avant la fin de la transition de vue.

L’entrée de l’historique et la position de défilement ont déjà été mises à jour lorsque cet événement est déclenché.

Événement `astro:page-load`

Un événement envoyé une fois le chargement d’une page terminé, qu’il s’agisse d’une navigation utilisant des transitions de vue ou native du navigateur.

Lorsque les transitions de vue sont activées sur la page, le code qui s’exécuterait normalement sur DOMContentLoaded doit être modifié pour s’exécuter sur cet événement.

Attributs des événements du cycle de vie

Ajouté à la version : astro@3.6.0

`info`

Type : URL

Données arbitraires définies lors de la navigation.

Il s’agit de la valeur littérale transmise à l’option info de la fonction navigate().

`sourceElement`

Type : Element | undefined

L’élément qui a déclenché la navigation. Il peut s’agir, par exemple, d’un élément <a> sur lequel on a cliqué.

Lors de l’utilisation de la fonction navigate(), ce sera l’élément spécifié dans l’appel.

`newDocument`

Type : Document

Le document de la page suivante dans la navigation. Le contenu de ce document sera échangé à la place du contenu du document actuel.

`navigationType`

Type : 'push' | 'replace' | 'traverse'

Quel type de navigation dans l’historique est en cours.

push : une nouvelle NavigationHistoryEntry est en cours de création pour la nouvelle page.
replace : l’actuelle NavigationHistoryEntry est remplacée par une entrée pour la nouvelle page.
traverse : aucune NavigationHistoryEntry n’est créée. La position dans l’historique change. La direction du parcours est donnée sur l’attribut direction

`direction`

Type : Direction

La direction de la transition.

forward : naviguer vers la page suivante de l’historique ou vers une nouvelle page.
back : naviguer vers la page précédente de l’historique.
Tout ce qu’un autre écouteur d’événement aurait pu définir.

`from`

Type : URL

L’URL de la page initiant la navigation.

`to`

Type : URL

L’URL de la page vers laquelle on navigue. Cette propriété peut être modifiée, la valeur à la fin du cycle de vie sera utilisée dans le NavigationHistoryEntry pour la page suivante.

`formData`

Type : FormData | undefined

Un objet FormData pour les requêtes POST.

Lorsque cet attribut est défini, une requête POST sera envoyée à l’URLto avec l’objet de données de formulaire donné comme contenu au lieu de la requête GET normale.

Lors de la soumission d’un formulaire HTML avec les transitions de vue activées, ce champ est automatiquement défini sur les données du formulaire. Lorsque vous utilisez la fonction navigate(), cette valeur est la même que celle donnée dans les options.

`loader()`

Type : () => Promise<void>

Implémentation de la phase suivante dans la navigation (chargement de la page suivante). Cette implémentation peut être surchargée pour ajouter un comportement supplémentaire.

`viewTransition`

Type : ViewTransition

L’objet de transition de vue utilisé dans cette navigation. Sur les navigateurs qui ne prennent pas en charge l’API de Transitions de Vue, il s’agit d’un objet implémentant la même API pour plus de commodité, mais sans l’intégration DOM.

`swap()`

Type : () => void

Mise en place de la logique d’échange de documents.

Apprenez-en davantage sur la façon de créer votre propre fonction d’échange personnalisée dans le guide Transitions de Vue.

Par défaut, cette implémentation appellera les fonctions suivantes dans l’ordre :

deselectScripts()
swapRootAttributes()
swapHeadElements()
saveFocus()
swapBodyElement()

Contribuer

Communauté

Référence de l'API de transitions de vue

Importations depuis astro:transitions

<ViewTransitions />

fade

slide

Importations depuis astro:transitions/client

navigate()

Option history

Option formData

Option info

Option state

Option sourceElement

supportsViewTransitions

transitionEnabledOnThisPage

getFallback()

swapFunctions

deselectScripts()

swapRootAttributes()

swapHeadElements()

saveFocus()

swapBodyElement()

Événements du cycle de vie

Événement astro:before-preparation

Événement astro:after-preparation

Événement astro:before-swap

Événement astro:after-swap

Événement astro:page-load

Attributs des événements du cycle de vie

info

sourceElement

newDocument

navigationType

direction

from

to

formData

loader()

viewTransition

swap()

Importations depuis `astro:transitions`

`<ViewTransitions />`

`fade`

`slide`

Importations depuis `astro:transitions/client`

`navigate()`

Option `history`

Option `formData`

Option `info`

Option `state`

Option `sourceElement`

`supportsViewTransitions`

`transitionEnabledOnThisPage`

`getFallback()`

`swapFunctions`

`deselectScripts()`

`swapRootAttributes()`

`swapHeadElements()`

`saveFocus()`

`swapBodyElement()`

Événement `astro:before-preparation`

Événement `astro:after-preparation`

Événement `astro:before-swap`

Événement `astro:after-swap`

Événement `astro:page-load`

`info`

`sourceElement`

`newDocument`

`navigationType`

`direction`

`from`

`to`

`formData`

`loader()`

`viewTransition`

`swap()`