Element : méthode scrollBy()

Syntaxe

scrollBy(xCoord, yCoord)
scrollBy(options)

Paramètres

xCoord

La valeur en pixels horizontale de la distance que vous souhaitez faire défiler.

yCoord

La valeur en pixels verticale de la distance que vous souhaitez faire défiler.

options

Un objet contenant les propriétés suivantes :

top Facultatif

Définit le nombre de pixels le long de l'axe Y pour faire défiler la fenêtre ou l'élément.

left Facultatif

Définit le nombre de pixels le long de l'axe X pour faire défiler la fenêtre ou l'élément.

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 résout 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 le même élément avant que le premier ne se termine.

Exemples

Utilisation simple

// défiler un élément
element.scrollBy(300, 300);

Utilisation de options :

element.scrollBy({
  top: 100,
  left: 100,
  behavior: "smooth",
});

Réagir à la fin du défilement

Notre démonstration des méthodes d'élément ^(angl.) (voir le code source ^(angl.)) montre comment la valeur de retour de promesse de scrollBy() peut être utilisée pour réagir à 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é CSS scroll-behavior de l'élément défilant sur smooth).

HTML

Notre HTML inclut un élément HTML <section> contenant plusieurs paragraphes de contenu et un élément HTML <div> barre d'outils contenant des éléments HTML <button> qui déclenchent diverses opérations de défilement sur le <section>.

<div>
  <button class="defilement">scroll() jusqu'à 1000</button>
  <button class="defilement-vers">scrollTo() en haut</button>
  <button class="defilement-par">scrollBy() de 200</button>
  <button class="defilement-dans-zone-visible">
    Faire défiler le dernier &lt;p&gt; dans la zone visible
  </button>
</div>

<section>…</section>

CSS

Nous donnons à l'élément <section> une hauteur (height) fixe et une valeur overflow-y de scroll afin qu'il défile verticalement, et définissons sa propriété CSS scroll-behavior sur smooth afin que toutes les opérations de défilement soient animées en douceur au fil du temps plutôt qu'instantanément.

section {
  border: 1px solid black;
  padding: 20px;
  margin-top: 60px;
  height: 500px;
  overflow-y: scroll;
  scroll-behavior: smooth;
}

Nous créons également deux sélecteurs de classe ; lorsque la 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 d'opacité (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 les références au <button> qui exécute l'opération scrollBy(), à la barre d'outils <div> et à la <section> défilante :

const btnDefilementPar = document.querySelector(".defilement-par");
const barreOutils = document.querySelector("div");
const section = document.querySelector("section");

Ensuite, nous définissons une fonction appelée estInterrompu(), conçue pour s'exécuter en réponse à la fin d'une opération de défilement, qui prend une valeur booléenne interrompu en paramètre. Elle affiche un message dans la console pour indiquer que le défilement est terminé et si l'opération a été interrompue (interrompu est true) ou non. De plus, si interrompu est true, elle appelle un alert() pour indiquer clairement l'interruption.

function estInterrompu(interrompu) {
  console.log(`Défilement terminé ;${interrompu ? " " : " non "}interrompu`);
  if (interrompu) {
    alert("Défilement interrompu !");
  }
}

Lorsque le bouton est cliqué, nous appliquons immédiatement la classe fade-out à la barre d'outils, ce qui la fait disparaître en douceur. Nous exécutons ensuite scrollBy(0, 200) sur le <section> pour faire défiler son contenu de 200 pixels vers le bas, en attendant la résolution de sa promesse et en stockant le resultat dans une constante. Lorsque la promesse est résolue, nous appelons estInterrompu() pour indiquer que l'opération de défilement est terminée et si elle a été interrompue. Enfin, nous appliquons la classe fade-in à la barre d'outils, ce qui la fait réapparaître en douceur.

btnDefilementPar.addEventListener("click", async () => {
  barreOutils.className = "fade-out";
  const resultat = await section.scrollBy(0, 200);
  estInterrompu(resultat.interrupted);
  barreOutils.className = "fade-in";
});

Le code non pertinent à scrollBy() n'est pas montré, pour des raisons de concision.

Résultat

Cliquez sur les boutons pour voir le comportement de défilement. Remarquez comment la barre d'outils disparaît en douceur lorsqu'un bouton est pressé, et réapparaît une fois le défilement en douceur terminé. Essayez également d'appuyer sur un bouton puis rapidement sur un autre bouton avant que la première opération de défilement ne soit terminée. Remarquez comment, dans ces cas, le défilement est signalé comme interrompu.

Vous pouvez également charger la démo 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 retournant une promesse, les opérations de défilement sont toujours fluides, mais la barre d'outils ne disparaît pas en douceur puis ne réapparaît pas une fois l'opération terminée. La détection des fonctionnalités est gérée par une fonction appelée supportsScrollPromises(), qui exécute une opération de défilement et teste si sa valeur de retour est une promesse :

function supportsScrollPromises() {
  const test = section.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