Pièges et solutions d'Astro View Transitions — Guide d'amélioration UX et qualité du code

Si menus ou recherche échouent seulement après navigation, comparez chargement direct et navigation ClientRouter, puis inspectez l’initialisation. Suivez le cycle de vie de Astro: View Transitions pour organiser les événements et vérifier doublons, retour et avance.

Introduction

Les View Transitions (ClientRouter) d’Astro sont une fonctionnalité puissante qui rend les transitions de page aussi fluides qu’une SPA. Cependant, dès leur introduction, on est confronté à des problèmes : le menu hamburger ne s’ouvre pas, le bouton de recherche ne répond pas, le slider s’arrête…

Cet article présente les pièges des View Transitions et leurs solutions, ainsi que des méthodes pratiques pour améliorer l’UX et la qualité du code.

---

Le problème des scripts avec View Transitions

Pourquoi les scripts cessent-ils de fonctionner ?

Une navigation classique recharge le HTML. Le ClientRouter modifie l’exécution : les scripts de module regroupés ne s’exécutent qu’une fois, tandis que les scripts en ligne peuvent être relancés lors de certaines navigations.

Les traitements affectés incluent :

• Ouverture/fermeture du menu hamburger
• Gestionnaires de clic du bouton de recherche
• Slider d’images hero
• Suivi du défilement de la table des matières
• Pattern façade des intégrations YouTube

Pattern de solution

Unifiez tous les scripts en fonctions nommées, réenregistrées via astro:after-swap.

<script>
  function initHeader() {
    const menuBtn = document.querySelector("[data-menu-toggle]");
    menuBtn?.addEventListener("click", () => {
      /* ... */
    });
  }

  // Exécution initiale
  initHeader();

  // Réexécution après View Transitions
  document.addEventListener("astro:after-swap", initHeader);
</script>

Distinction entre astro:after-swap et astro:page-load

• astro:after-swap : se déclenche immédiatement après le remplacement du DOM. Ne se déclenche pas au chargement initial, il faut donc appeler la fonction directement
• astro:page-load : se déclenche à la fois au chargement initial et après les View Transitions. Permet d’omettre l’appel initial explicite

Pour les intégrations YouTube qui doivent fonctionner dès le chargement initial, astro:page-load est plus pratique.

---

Introduction de la recherche plein texte Pagefind

Pour implémenter une recherche plein texte sur un site statique, Pagefind est recommandé. L’index est généré au build et la recherche est exécutée côté navigateur — sans serveur et rapide.

Configuration de base

{
  "scripts": {
    "build": "astro build && pagefind --site dist"
  }
}

Exécutez Pagefind après le build d’Astro pour générer l’index dans dist/pagefind/.

Recherche à facettes

Les attributs data-pagefind-filter permettent le filtrage sur 3 axes : auteur, année et tag.

<span data-pagefind-filter="author">gui</span>
<span data-pagefind-filter="year">2026</span>
<span data-pagefind-filter="tag">Astro</span>

Modale de recherche

Implémentez une modale de recherche s’ouvrant avec le raccourci Ctrl+K. En cas de zéro résultat, affichez des liens vers la liste des articles, la page des services et la page de contact pour éviter le départ de l’utilisateur.

Intégration SearchAction

Google a supprimé le champ de recherche des liens de site en 2024-11 (annonce officielle). Considérez SearchAction comme une ancienne implémentation, sans attendre ce champ dans les résultats. Ouvrir la modale via ?q= reste utile pour les liens partagés et la recherche interne.

Configuration du cache

Les fichiers d’index Pagefind sont peu fréquemment modifiés — activez le cache via les en-têtes de Cloudflare Pages.

/pagefind/*
  Cache-Control: public, max-age=604800, stale-while-revalidate=86400

---

Élimination des onclick en ligne

Les onclick="..." directement dans le HTML sont pratiques mais requièrent unsafe-inline dans le CSP (Content Security Policy).

Pattern d’amélioration

Remplacez onclick par des attributs data-* + addEventListener.

<!-- Avant -->
<button onclick="window.openSearch?.()">Rechercher</button>

<!-- Après -->
<button data-search-trigger>Rechercher</button>

document.querySelectorAll("[data-search-trigger]").forEach((btn) => {
  btn.addEventListener("click", () => window.openSearch?.());
});

---

Mise en place d’une bibliothèque de composants

Disposer de composants utilisables lors de la rédaction d’articles de blog enrichit l’expression des articles.

Composant	Usage
Callout	4 types d’annotations : info / warning / tip / note
Timeline	Affichage chronologique d’événements
FAQ	Questions-réponses avec données structurées
Gallery	Galerie d’images avec Lightbox
CompareTable	Tableau de comparaison avant/après
ProcessFigure	Schéma de processus étape par étape
LinkCard	Carte de lien externe style OGP
YouTubeEmbed	Chargement différé avec pattern façade

Tous ces composants sont conçus pour être invocables depuis le frontmatter du Markdown. Le template affiche <Callout> si data.callout existe.

---

Amélioration de la sécurité des types TypeScript

Élimination des types any

Remplacez any[] par CollectionEntry<'blog'>[] pour des types concrets. L’autocomplétion IDE et la détection d’erreurs à la compilation fonctionnent, rendant l’accès aux propriétés dans les templates sûr.

Types littéraux pour le schéma de contenu

type: z.enum(["info", "warning", "tip", "note"]).default("info");

En définissant les valeurs du frontmatter comme union de types littéraux, les branchements if (callout.type === 'info') côté template deviennent type-safe.

Assertion as const

L’ajout de as const aux objets constants rend les propriétés readonly et l’inférence de type littérale. Appliquez-le systématiquement à la constante SITE.

Migration des imports dépréciés

La documentation actuelle d’Astro importe z pour les schémas de contenu depuis astro/zod. Consultez le guide des collections de contenu.

---

Gestion centralisée des constantes

Les valeurs codées en dur sont source d’oublis lors des modifications. Les valeurs suivantes ont été centralisées dans src/data/site.ts.

Constante	Nombre d’occurrences avant
AdSense Client ID	4 fichiers
GA4 Measurement ID	2 emplacements
ID de slot publicitaire	4 fichiers
URLs sociales (X, GitHub, Discord, Aceserver)	17 emplacements
Téléphone, email, LINE	3 fichiers

export const SITE = {
  name: "Acecore",
  url: "https://acecore.net",
  ga4Id: "G-XXXXXXXXXX",
  adsenseClientId: "ca-pub-XXXXXXXXXXXXXXXX",
  social: {
    x: "https://x.com/acecore",
    github: "https://github.com/acecore-systems",
    discord: "https://discord.gg/...",
  },
} as const;

---

Autres améliorations UX

Suivi du défilement de la table des matières

IntersectionObserver surveille les titres du contenu et met en surbrillance le titre actif dans la table des matières de la barre latérale. Le point clé est d’utiliser scrollIntoView({ block: 'nearest', behavior: 'smooth' }) pour faire défiler la table des matières elle-même.

Scroll spy

Pour les pages à structure single-page comme la page de services, IntersectionObserver suit automatiquement l’élément actif de la navigation.

Pagination

Pagination automatique par lots de 6 articles, navigation avec points de suspension (1 2 ... 9 10), liens textuels « ← Précédent » et « Suivant → ». La logique de pagination est mutualisée dans src/utils/pagination.ts.

Liens d’ancrage avec en-tête sticky

Un en-tête fixe peut masquer la cible d’une ancre. L’exemple de preflight UnoCSS ci-dessous correspond à la configuration utilisée à l’époque ; avec Tailwind aujourd’hui, appliquez une règle CSS équivalente.

[id] {
  scroll-margin-top: 5rem;
}
html {
  scroll-behavior: smooth;
}

---

Conclusion

Si vous utilisez les View Transitions, l’unification du pattern d’initialisation des scripts est primordiale. Comprenez la distinction entre astro:after-swap / astro:page-load et testez toutes les interactions.

Côté qualité du code, la sécurité des types TypeScript et la gestion centralisée des constantes contribuent grandement à la maintenabilité à long terme. Cela semble fastidieux au début, mais les bénéfices de l’autocomplétion IDE se ressentent au quotidien dans le développement.

---

Série d’articles associée

Cet article fait partie de la série « Guide d’amélioration de la qualité d’un site Astro ». Les améliorations de performance, SEO et accessibilité sont présentées dans des articles dédiés.

Ajout du 6 octobre 2026 : affichage et état des actions dans l’éditeur

Dans une modification anonymisée de l’éditeur, la navigation entre catégories sur petit écran, la navigation fixe, les indications au clavier, les libellés des champs et le focus ont été ajustés. L’état public ou privé suit également l’état de l’API et l’instantané public au lieu d’être déduit de l’apparence du bouton.

Si le contexte d’authentification ou le contrat entre le frontend et le backend manque, l’interface n’annonce pas que l’enregistrement a réussi ; elle indique qu’il faut recharger la page ou se réauthentifier. Une interface d’import vide et soignée ne prouve pas la recette complète de l’import de données réelles, de leur enregistrement et de leur publication. Le périmètre d’entrée est décrit dans Import de profil et les limites du CSS public dans Conception sûre des thèmes.

Lorsqu’on réorganise les noms ou les catégories, il faut aligner les valeurs existantes, l’API, les filtres et les modifications de la base de données. S’il n’existe aucune ancienne donnée, il ne faut pas prétendre qu’un contenu réel a été migré. Si un badge d’état mène à une vue détaillée, cette action doit fonctionner au clic comme avec la touche Entrée. Pour la modification en ligne d’un identifiant d’URL publique, conservez aussi les vérifications du format, des doublons et de la mise à jour de l’URL. L’affichage public, la lecture des médias et l’invitation à se connecter en mode anonyme ont été vérifiés séparément de la recette de l’enregistrement de l’identifiant ou du changement d’état public dans l’éditeur connecté.

Lorsqu’on réorganise l’espace d’édition selon les nouvelles tâches de la personne, on distingue la navigation persistante de l’espace de travail ; renommer les commandes sans retirer les anciennes ne suffit pas. Les valeurs auxiliaires, comme un solde, peuvent être moins visibles que les actions principales, mais leur taille de texte et leur contraste doivent rester lisibles.

1. 1 Action dans l’éditeur Déplacer une catégorie ou choisir une unité de travail modifie l’état de l’espace d’édition.
2. 2 API et snapshot publié Vérifiez le résultat de l’API et le snapshot public. N’affichez pas de succès si la requête échoue ou si le contexte d’authentification manque.
3. 3 État après rechargement N’affichez que l’état confirmé et demandez un rechargement ou une nouvelle authentification si nécessaire. L’acceptation de l’enregistrement et de la publication par des utilisateurs connectés reste non vérifiée.