Window : méthode scrollTo()

Syntaxe

scrollTo(xCoord, yCoord)
scrollTo(options)

Paramètres

xCoord

La coordonnée horizontale du document vers laquelle vous voulez que le bord gauche de la fenêtre de visualisation défile.

yCoord

La coordonnée verticale du document vers laquelle vous voulez que le bord supérieur de la fenêtre de visualisation défile.

options

Un objet contenant les propriétés suivantes :

top Facultatif

La coordonnée verticale du document vers laquelle vous voulez que le bord supérieur de la fenêtre de visualisation défile. C'est la même que le paramètre yCoord.

left Facultatif

La coordonnée horizontale du document vers laquelle vous voulez que le bord gauche de la fenêtre de visualisation défile. C'est la même que le paramètre xCoord.

behavior Facultatif

Détermine si le défilement est instantané ou s'il s'anime en douceur. Cette option est une chaîne de caractères qui doit prendre l'une des valeurs suivantes :

• smooth : Le défilement s'anime en douceur.
• instant : Le défilement se produit instantanément en un seul saut.
• auto : Le comportement de défilement est déterminé par la valeur calculée de la propriété CSS scroll-behavior sur l'élément.

Si omis, behavior prend par défaut la valeur auto.

Valeur de retour

Une promesse (Promise) qui se complète avec un objet contenant la propriété suivante :

interrupted

Une valeur booléenne indiquant si l'opération de défilement a été interrompue (true) ou non (false). Une telle interruption se produit généralement lorsqu'un défilement programmé est en cours et qu'un autre défilement programmé est initié sur la fenêtre avant que le premier ne se termine.

Exemples

Utilisation simple

window.scrollTo(0, 1000);

Avec options :

window.scrollTo({
  top: 100,
  left: 100,
  behavior: "smooth",
});

Répondre à la fin du défilement

Notre démonstration des méthodes de la fenêtre ^(angl.) (voir le code source ^(angl.)) montre comment la valeur de retour de promesse de scrollTo() peut être utilisée pour répondre à la fin d'une opération de défilement. Cette technique est surtout utile dans les cas où le défilement se produit en douceur au fil du temps (obtenu en définissant l'option behavior sur smooth, ou en définissant la propriété scroll-behavior de l'élément défilant sur smooth).

HTML

Notre HTML inclut plusieurs paragraphes de contenu et une barre d'outils <div> contenant des éléments HTML <button> qui déclenchent diverses opérations de défilement sur la fenêtre.

<div>
  <button class="scroll">scroll() à 1000</button>
  <button class="scroll-to">scrollTo() haut de page</button>
  <button class="scroll-by">scrollBy() de 200</button>
</div>

<p>…</p>

<p>…</p>

…

CSS

Nous donnons à l'élément :root une valeur de propriété scroll-behavior de smooth afin que toutes les opérations de défilement soient animées en douceur au fil du temps plutôt qu'immédiatement.

:root {
  scroll-behavior: smooth;
}

Nous créons également deux sélecteurs de classe : lorsqu'une classe fade-out ou fade-in est appliquée à un élément, une animation est appliquée afin qu'il disparaisse ou apparaisse en douceur, respectivement. Nous définissons également des blocs @keyframes pour définir les changements de opacity requis pour ces animations.

.fade-out {
  animation: fade-out 0.3s linear both;
}

.fade-in {
  animation: fade-in 0.3s linear both;
}

@keyframes fade-out {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

@keyframes fade-in {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

Le reste du CSS n'est pas montré, pour des raisons de concision.

JavaScript

Nous commençons par récupérer des références au <button> qui exécute l'opération scrollTo() et à la barre d'outils <div> :

const btnDefilementA = document.querySelector(".scroll-to");
const barreOutils = document.querySelector("div");

Ensuite, nous définissons une fonction appelée estInterrompu(), conçue pour s'exécuter lorsqu'une opération de défilement se termine et qui prend une valeur booléenne interrompu en paramètre. Elle consigne un message dans la console pour indiquer que le défilement est terminé et préciser si l'opération a été interrompue (interrompu vaut true) ou non. En outre, si interrompu vaut true, elle appelle alert() pour signaler clairement l'interruption.

function estInterrompu(interrompu) {
  console.log(
    `Le défilement est terminé ;${interrompu ? " " : " non "}interrompu`,
  );
  if (interrompu) {
    alert("Le défilement a été interrompu !");
  }
}

Lorsque le bouton est activé, nous appliquons immédiatement la classe fade-out à la barre d'outils, ce qui la fait disparaître en fondu. Nous exécutons ensuite scrollTo(0, 0) sur la fenêtre pour faire défiler son contenu jusqu'en haut, tout en attendant la résolution de sa promesse et en stockant le resultat dans une constante. Une fois la promesse résolue, nous appelons estInterrompu() pour indiquer que l'opération de défilement est terminée et préciser si elle a été interrompue. Enfin, nous appliquons la classe fade-in à la barre d'outils, ce qui la fait réapparaître en fondu.

btnDefilementA.addEventListener("click", async () => {
  barreOutils.className = "fade-out";
  const resultat = await window.scrollTo(0, 0);
  estInterrompu(resultat.interrupted);
  barreOutils.className = "fade-in";
});

Le code qui n'est pas lié à scrollTo() n'est pas affiché, par souci de concision.

Résultat

Activez les boutons pour observer le comportement du défilement. Notez que la barre d'outils disparaît en fondu lorsqu'un bouton est activé, puis réapparaît une fois le défilement fluide terminé. Essayez aussi d'activer un bouton, puis d'en activer rapidement un autre avant la fin de la première opération de défilement. Notez que, dans ces cas, le défilement est signalé comme interrompu.

Vous pouvez aussi ouvrir la démonstration dans un onglet séparé ^(angl.) et consulter le code source ^(angl.).

Aparté sur la détection des fonctionnalités

Si vous exécutez cet exemple dans un navigateur qui ne prend pas en charge les opérations de défilement qui retournent une promesse, les opérations de défilement restent fluides, mais la barre d'outils ne disparaît pas en fondu puis ne réapparaît pas en fondu une fois l'opération terminée. Une fonction appelée supportsScrollPromises() assure la détection des fonctionnalités, exécute une opération de défilement et vérifie si sa valeur de retour est une promesse :

function supportsScrollPromises() {
  const test = window.scroll(0, 0);
  return test instanceof Promise;
}

Consultez le code source ^(angl.) pour voir comment la détection des fonctionnalités est utilisée.

Spécifications

Compatibilité des navigateurs

Voir aussi

• La méthode Window.scroll()
• La méthode Window.scrollBy()
• La méthode Element.scrollTo()
• La méthode Window.scrollByLines()
• La méthode Window.scrollByPages()