jQuery / Méthode / .scrollTop() - Lire ou définir la position de défilement

Dans jQuery, .scrollTop() lit la position verticale de la première cible sélectionnée ; .scrollTop(120) la définit sur toutes les cibles. Sélectionnez $(window) pour la page ou l’élément pour un conteneur intérieur. Ce n’est pas la position de l’élément dans le document.

Choisir la cible du défilement

L’API .scrollTop() mesure en pixels CSS le contenu masqué au-dessus de la zone. Dans un flux ordinaire de haut en bas, zéro est le début et la valeur augmente vers le bas. Elle ne représente ni la position visuelle du curseur de défilement ni CSS top.

Les lectures natives sont Element.scrollTop et window.scrollY. Ici jQuery emploie une méthode pour les deux. Lire ne déplace pas la vue.

Exemple complet : page et boîte

Enregistrez tout le code en UTF-8 dans scroll-demo.html et ouvrez-le dans le navigateur. Internet est nécessaire pour le fichier jQuery officiel 4.0.0 du réseau de diffusion de contenu (CDN), sans installation. Positions, demandes excessives, réinitialisation et console ont été exécutées avec 3.7.1 et 4.0.0 dans Edge sous Windows.

Le document mesure au moins 2000px ; la boîte est à top 500px du document. Six lignes de 100px donnent 600px de contenu pour 160px de hauteur intérieure visible : maximum 600 - 160 = 440px. Les bordures sont hors de cette hauteur. scroll-behavior:auto permet une comparaison directe.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Separate page and element scroll positions</title>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
  <style>
    html { scroll-behavior: auto; }
    body { margin: 0; min-height: 2000px; font: 16px/1.6 sans-serif; }
    #controls { position: fixed; top: 0; left: 0; right: 0; z-index: 2; background: #fff; padding: 12px; max-height: 42vh; overflow: auto; }
    button { font: inherit; margin: 3px; }
    pre { white-space: pre-wrap; overflow-wrap: anywhere; }
    #box { position: absolute; top: 500px; left: 20px; right: 20px; max-width: 600px; height: 160px; overflow-y: auto; border: 2px solid teal; scroll-behavior: auto; }
    .row { height: 100px; box-sizing: border-box; padding: 12px; border-bottom: 1px solid #abc; background: #edf9f6; }
  </style>
</head>
<body>
  <div id="controls">
    <strong>Page and box scrolling</strong>
    <button type="button" id="box120">Box to 120</button>
    <button type="button" id="bottom">Box to bottom</button>
    <button type="button" id="page300">Page to 300</button>
    <button type="button" id="reset">Reset both</button>
    <pre id="result" aria-live="polite"></pre>
  </div>
  <div id="box" tabindex="0" aria-label="Scrollable example rows">
    <div class="row">Alpha</div><div class="row">Beta</div><div class="row">Gamma</div><div class="row">Delta</div><div class="row">Epsilon</div><div class="row">Zeta</div>
  </div>
  <script>
    $(function () {
      const $box = $("#box");
      function report() {
        const node = $box.get(0);
        const top = $box.scrollTop();
        const max = Math.max(0, node.scrollHeight - node.clientHeight);
        const bottom = max > 0 && Math.abs(max - top) <= 1;
        $("#result").text(`window=${$(window).scrollTop()}\nbox=${top}\nbox max=${max}\nat bottom=${bottom}`);
      }
      $("#box120").on("click", function () { $box.scrollTop(120); report(); });
      $("#bottom").on("click", function () { $box.scrollTop(1000000); report(); });
      $("#page300").on("click", function () { $(window).scrollTop(300); report(); });
      $("#reset").on("click", function () { $box.scrollTop(0); $(window).scrollTop(0); report(); });
      $box.on("scroll.scrollLesson", report);
      $(window).on("scroll.scrollLesson resize.scrollLesson", report);
      report();
    });
  </script>
</body>
</html>

Cette sortie suppose les deux positions au début. Si votre zone visible dépasse 2000px sans débordement de page, réduisez sa hauteur pour tester le défilement.

window=0
box=0
box max=440
at bottom=false

1. Box to 120 donne box=120 et conserve window=0. Une partie d’Alpha disparaît au-dessus.
2. Page to 300 donne window=300, box=120. Déplacer la boîte à l’écran diffère de déplacer son contenu.
3. Box to bottom demande 1000000, mais cette boîte normale limite à 440. at bottom devient true.
4. Défilement direct ou clavier dans la boîte actualise son événement scroll. Les commandes fixes gardent les valeurs disponibles.
5. Reset both remet séparément boîte et fenêtre à zéro, même après plusieurs utilisations.

Inscrivez scroll directement sur l’élément qui défile. window scroll ne traite pas automatiquement le conteneur intérieur. report() lit les deux positions et recalcule le maximum.

Maximum, bas et plusieurs éléments

Pour une boîte verticale ordinaire, le maximum est Math.max(0, scrollHeight - clientHeight). scrollHeight mesure le contenu et clientHeight l’intérieur visible. L’exemple demande un maximum positif et au plus 1px de différence pour signaler le bas, plutôt qu’une égalité stricte avec des valeurs fractionnaires.

Sans débordement, une demande peut laisser zéro. Ici at bottom reste false ; considérer une boîte courte comme déjà en bas dépend de l’interface. Images, polices et redimensionnements peuvent changer hauteur et maximum.

Exécutez ceci dans la console de la même page. Deux boîtes temporaires reçoivent des positions différentes. Lire la collection donne la première ; définir 80 change les deux. La zone temporaire est ensuite supprimée.

const $holder = $("<div>").appendTo("body");
const $boxes = $("<div></div><div></div>").css({ height: 40, overflowY: "auto" }).appendTo($holder);
$boxes.each(function () { $(this).append($("<div>").css("height", 200)); });
$boxes.eq(0).scrollTop(40);
$boxes.eq(1).scrollTop(100);
console.log(`first getter=${$boxes.scrollTop()}`);
$boxes.scrollTop(80);
console.log(`all=${$boxes.map(function () { return $(this).scrollTop(); }).get().join(",")}`);
console.log(`empty getter=${typeof $().scrollTop()}`);
$holder.remove();

first getter=40
all=80,80
empty getter=undefined

Une sélection vide renvoie undefined. Zéro est une position valide, pas une absence de cible. Vérifiez .length, l’élément défilant et la préparation du modèle objet du document (DOM).

Comprendre une absence de déplacement

overflow-y:auto ne suffit pas si la boîte grandit avec son contenu. Vérifiez hauteur ou hauteur maximale avec scrollHeight/clientHeight. Si un ancêtre défile et que vous sélectionnez l’enfant, celui-ci peut rester à zéro.

Utilisez window pour distinguer la page des conteneurs. Définir un nombre ne demande pas une animation jQuery temporisée. Du CSS de défilement doux ou d’autres effets peut modifier le timing : ne prenez pas une lecture intermédiaire pour le résultat final.

Les valeurs ne sont pas toujours entières ou positives. MDN décrit fractions, valeurs négatives avec column-reverse et dépassements de Safari. La plage vérifiée 0–440 concerne cette boîte normale dans Edge. Pour d’autres dispositions, vérifiez d’abord direction et comportement du navigateur.