Optimiser les Animations Web
Règle Fondamentale
Mesurez la vraie page avant d'éditer. Le but n'est pas de supprimer le mouvement, mais d'arrêter le travail hors écran, de reprendre correctement le mouvement visible, et de libérer les ressources persistantes lors du nettoyage de route/démontage.
Utilisez Codex Browser lorsque disponible, surtout pour les pages localhost. N'utilisez pas Chrome sauf demande explicite de l'utilisateur.
Workflow
-
Inspecter le contexte du dépôt.
- Lisez
AGENTS.mdou les instructions locales. - Exécutez
git status --shorttôt. - Trouvez les composants de page, les hooks d'animation, les keyframes CSS,
requestAnimationFrame,setInterval,setTimeout, les composants canvas/WebGL/physique, les éléments média, les timelines/tweens GSAP et les utilitaires de visibilité existants. - Recherchez le nettoyage des effets : écouteurs d'événements, observateurs, boucles RAF, intervalles, timers, scripts externes, flux médias, textures/matériaux/géométries/rendus WebGL, et travaux asynchrones pouvant se terminer après le démontage.
- Si l'arbre de travail est sale, planifiez un staging étroit dès le départ.
- Lisez
-
Capturer une baseline dans le navigateur.
- Ouvrez la route exacte nommée par l'utilisateur.
- Profitez en haut, au milieu, en bas/contenu inférieur, et sur une fenêtre mobile si la disposition peut différer.
- Comptez les animations CSS via
animationName,animationPlayStateet la visibilité. Incluez::beforeet::after. - Inspectez les éléments canvas/WebGL séparément ; le profilage CSS ne prouve pas que les boucles RAF se sont arrêtées.
- Enregistrez quels noms d'animations tournent hors écran et les propriétaires DOM responsables.
- Pour les demandes de mémoire/fuite, enregistrez également les comptages d'éléments/canvas/images/iframes, les métriques heap JS exposées si disponibles, un échantillon au repos après 10-30 secondes, et un court échantillon de cycle de route. Si les API heap retournent
nullou que le sandbox du navigateur bloque le monkey-patching, dites-le et basez-vous sur des comptages stables observables plus l'audit du code source. - Limitez les tests de stress. Un crash d'onglet pendant le profilage est une preuve de surcharge, mais ne sur-attribuez pas la cause sauf si elle est reproduite par un test minimal.
- Voir
references/browser-profiling.mdpour un évaluateur Codex Browser réutilisable.
-
Patcher le plus petit propriétaire qui contrôle le mouvement.
- Privilégiez un hook de révélation/visibilité de page existant si l'application en a un.
- Sinon, ajoutez un
IntersectionObserverqui bascule une classe stable telle queis-offscreensur les sections et les éléments enfants animés. - Mettez en pause les animations CSS avec des règles ciblées :
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- Pour les cartes répétées ou les placeholders, observez la coque de la carte et les descendants animés, pas tout le document.
- Pour les pistes de marquee/ticker, mettez la piste en pause lorsque sa section est hors écran.
- Pour les squelettes et les lueurs de pseudo-éléments, incluez les sélecteurs de pause
::beforeet::aftersi nécessaire. - Pour les boucles canvas/WebGL/physique, contrôlez la boucle RAF directement :
- Démarrez lorsque le canvas/conteneur intersecte.
- Annulez
requestAnimationFramequand il est hors écran. - Reprenez lors de la ré-entrée.
- Déconnectez les observateurs et annulez les frames lors du nettoyage.
- Ajoutez un marqueur de débogage non visuel comme
data-animation-activelorsque cela aide la vérification dans le navigateur.
- Respectez
prefers-reduced-motionsi le composant le fait déjà, et évitez d'introduire des boucles de rendu React pour l'état de défilement/d'animation. - Pour le renforcement contre les fuites :
- Effacez chaque timeout/interval créé par l'effet.
- Annulez RAF avant le démontage et avant de redémarrer une boucle.
- Déconnectez
IntersectionObserver,ResizeObserver,MutationObserveret les abonnements personnalisés. - Supprimez les écouteurs globaux/window/document avec la même référence de handler.
- Disposez les textures/matériaux/géométries/rendus Three/WebGL et supprimez les nœuds DOM du rendu.
- Tuez les tweens/timelines GSAP pour les nœuds DOM et les objets mutables comme les uniforms de shader.
- Arrêtez les flux médias et mettez en pause les sources vidéo/audio détachées.
- Protégez les chargeurs asynchrones avec un drapeau
isDisposedet disposez les ressources chargées si elles se résolvent après le démontage. - Dans le nettoyage React, capturez les valeurs
ref.currentdans l'effet avant de retourner le nettoyage si le lint avertit que la ref peut changer. - Limitez les deltas de trame de physique ou simulation après les pauses de visibilité pour que les trames retardées n'exécutent pas de mises à jour surdimensionnées.
-
Vérifier le comportement, pas seulement les builds.
- Rechargez la route et réexécutez les mêmes profils haut/milieu/bas/mobile.
- Résultat cible :
offscreenRunningCount: 0pour les sections de page testées. - Confirmez que les animations visibles tournent encore ou reprennent lorsqu'on fait défiler pour les voir.
- Confirmez que les boucles RAF/canvas signalent inactives hors écran et actives dans la vue, ou prouvez autrement la cancellation depuis l'état source/runtime.
- Pour les audits de fuite, comparez les cycles de route avant/après et les échantillons au repos. Les comptages DOM/canvas/images doivent revenir à la même baseline après une navigation répétée, en tenant compte de petits changements asynchrones attendus.
- Exercez une interaction de page normale comme la recherche/le filtrage/la navigation pour que l'observateur ne casse pas le contenu dynamique.
- Vérifiez les avertissements/erreurs de la console dans un nouvel onglet.
-
Effectuer des vérifications locales.
- Utilisez les portes normales du dépôt. Pour les applications React/Vite, c'est souvent :
git diff --check
npm run lint
npm run build
- Mentionnez séparément les avertissements non fatals connus des échecs.
- Commiter étroitement lorsque demandé par le dépôt ou les instructions de l'utilisateur.
- Si des modifications sales non liées existent, utilisez un index isolé :
rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# Appliquez uniquement les morceaux souhaités à l'index temporaire.
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "Pause offscreen <page> animations"
git restore --staged <files> 2>/dev/null || true
- Ne staguez jamais des fichiers larges depuis un arbre de travail sale sauf si chaque morceau appartient à la tâche.
- Rapporter avec des preuves.
- Commencez par les conclusions : ce qui tournait encore, ce qui semblait sujet aux fuites, et ce qui n'a pas pu être mesuré.
- Séparez les risques d'audit du code source des mesures en direct dans le navigateur.
- Incluez la route exacte échantillonnée, le nombre d'animations hors écran, la stabilité des comptages DOM/canvas, le résultat du cycle de route, et les vérifications locales.
- Énoncez clairement les limites, en particulier les compteurs heap indisponibles ou l'instrumentation bloquée par le navigateur.
Bons Patrons de Correction
is-offscreenau niveau section ETis-offscreenau niveau élément pour les longues sections où les animations enfants en dessous du pli peuvent encore tourner.- Constantes de sélecteur de visibilité partagées par route, comme
COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR. - Seuils
IntersectionObserverautour de0.01pour le contrôle d'animation. - Contrôle direct de la boucle RAF pour les effets WebGL/canvas ;
animation-play-stateCSS ne peut pas mettre en pause les boucles de rendu JavaScript. - Limites de delta de trame pour les boucles de physique qui reprennent après une trame en pause ou retardée.
- Nœuds de nettoyage capturés pour les refs React utilisées par les effets GSAP/WebGL.
- Garde
isDisposedpour les chargeurs d'image/vidéo/texture/données qui peuvent se résoudre après le démontage. - Sondes courtes au repos et de cycle de route pour attraper l'accumulation de nœuds DOM, canvases, iframes ou médias non libérés.
À Éviter
- Supprimer toutes les animations pour faire passer le profil.
- Mettre en pause le mouvement héroïque visible parce qu'un sélecteur ancêtre est trop large.
- Supposer que
animation-play-statecouvre les pseudo-éléments ou les boucles RAF JavaScript. - Se fier à une unique mesure en haut de page sur les longues pages.
- Considérer les compteurs heap indisponibles comme une preuve qu'il n'y a pas de fuite mémoire.
- Exécuter des boucles de stress illimitées dans le navigateur ; utilisez des cycles limités et enregistrez les crashes sans sur-affirmer la causalité.
- Utiliser des captures d'écran seules comme preuve de performance.
- Laisser traîner des morceaux locaux non liés dans le commit.