Window: scrollBy() Methode

Syntax

scrollBy(xCoord, yCoord)
scrollBy(options)

Parameter

xCoord

Der horizontale Pixelwert, um den Sie scrollen möchten.

yCoord

Der vertikale Pixelwert, um den Sie scrollen möchten.

options

Ein Objekt, das die folgenden Eigenschaften enthält:

top Optional

Gibt die Anzahl der Pixel auf der Y-Achse an, um die das Fenster oder Element gescrollt werden soll.

left Optional

Gibt die Anzahl der Pixel auf der X-Achse an, um die das Fenster oder Element gescrollt werden soll.

behavior Optional

Bestimmt, ob das Scrollen sofort erfolgt oder sanft animiert wird. Diese Option ist ein String, der einen der folgenden Werte annehmen muss:

• smooth: Das Scrollen wird sanft animiert.
• instant: Das Scrollen erfolgt sofort in einem einzigen Sprung.
• auto: Das Scrollverhalten wird durch den berechneten Wert der scroll-behavior-CSS-Eigenschaft des Elements bestimmt.

Wird behavior weggelassen, ist der Standardwert auto.

Rückgabewert

Ein Promise, das mit einem Objekt erfüllt wird, das die folgende Eigenschaft enthält:

interrupted

Ein boolescher Wert, der angibt, ob der Scrollvorgang unterbrochen wurde (true) oder nicht (false). Eine solche Unterbrechung tritt typischerweise auf, wenn ein programmatischer Scrollvorgang in Gang ist und ein weiterer programmatischer Scrollvorgang auf dem Fenster initiiert wird, bevor der erste abgeschlossen ist.

Beispiele

Grundlegende Verwendung

Um eine Seite nach unten zu scrollen:

window.scrollBy(0, window.innerHeight);

Um nach oben zu scrollen:

window.scrollBy(0, -window.innerHeight);

Verwendung von options:

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

Reagieren auf das Ende des Scrollens

Unsere Fenstermethoden-Demo (Quellcode ansehen) zeigt, wie der Promise-Rückgabewert von scrollBy() verwendet werden kann, um auf das Ende eines Scrollvorgangs zu reagieren. Diese Technik ist hauptsächlich in Fällen nützlich, in denen das Scrollen über die Zeit hinweg sanft erfolgt (erreicht durch die Einstellung der behavior-Option auf smooth oder durch das Setzen der scroll-behavior-Eigenschaft des Scroll-Elements auf smooth).

HTML

Unser HTML enthält mehrere Absätze Inhalt und ein <div>-Element-Toolbar mit <button>-Elementen, die verschiedene Scrollvorgänge im Fenster auslösen.

<div>
  <button class="scroll">scroll() to 1000</button>
  <button class="scroll-to">scrollTo() top</button>
  <button class="scroll-by">scrollBy() 200</button>
</div>

<p>...</p>

<p>...</p>

...

CSS

Wir geben dem :root-Element einen Wert der scroll-behavior-Eigenschaft von smooth, sodass alle Scrollvorgänge über die Zeit hinweg sanft animiert werden, anstatt sofort zu erfolgen.

:root {
  scroll-behavior: smooth;
}

Wir erstellen auch zwei Klassenselektoren; wenn eine fade-out- oder fade-in-Klasse auf ein Element angewendet wird, wird eine animation angewendet, sodass sie sanft aus- oder eingeblendet wird. Wir definieren auch @keyframes-Blöcke, um die erforderlichen opacity-Änderungen für diese Animationen zu definieren.

.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;
  }
}

Der Rest des CSS wird aus Gründen der Kürze nicht angezeigt.

JavaScript

Wir beginnen damit, Referenzen auf die <button>, die den scrollBy()-Vorgang ausführen, und die Toolbar-<div> zu erfassen:

const scrollByBtn = document.querySelector(".scroll-by");
const toolbar = document.querySelector("div");

Als Nächstes definieren wir eine Funktion namens isInterrupted(), die als Reaktion darauf ausgeführt wird, dass ein Scrollvorgang endet und die einen booleschen interrupted-Wert als Parameter nimmt. Sie protokolliert eine Nachricht in der Konsole, um zu sagen, dass das Scrollen beendet ist und ob der Vorgang unterbrochen wurde (interrupted ist true) oder nicht. Außerdem wird, falls interrupted true ist, ein alert() ausgeführt, um die Unterbrechung deutlich anzuzeigen.

function isInterrupted(interrupted) {
  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
  if (interrupted) {
    alert("Scroll interrupted!");
  }
}

Wenn die Schaltfläche geklickt wird, wenden wir sofort die fade-out-Klasse auf die Toolbar an, sodass sie ausblendet. Danach führen wir scrollBy(0, 200) auf dem Fenster aus, um dessen Inhalt um 200 Pixel nach unten zu scrollen, warten auf die Auflösung des Promises und speichern das result in einer Konstante. Wenn das Promise aufgelöst wurde, nennen wir isInterrupted(), um zu melden, dass der Scrollvorgang abgeschlossen ist und ob er unterbrochen wurde. Schließlich wenden wir die fade-in-Klasse auf die Toolbar an, wodurch sie wieder eingeblendet wird.

scrollByBtn.addEventListener("click", async () => {
  toolbar.className = "fade-out";
  const result = await window.scrollBy(0, 200);
  isInterrupted(result.interrupted);
  toolbar.className = "fade-in";
});

Der nicht relevante Code für scrollBy() wird aus Gründen der Kürze nicht angezeigt.

Ergebnis

Klicken Sie auf die Schaltflächen, um das Scrollverhalten zu sehen. Beachten Sie, wie sich die Toolbar ausblendet, wenn eine Schaltfläche gedrückt wird, und sich wieder einblendet, sobald das sanfte Scrollen beendet ist. Versuchen Sie auch, eine Schaltfläche zu drücken und schnell eine andere Schaltfläche zu drücken, bevor der erste Scrollvorgang beendet ist. Beachten Sie, wie in diesen Fällen das Scrollen als unterbrochen gemeldet wird.

Sie können das Demo auch in einem separaten Tab laden und den Quellcode ansehen.

Hinweis zur Funktionserkennung

Wenn Sie dieses Beispiel in einem Browser ausführen, der keine Promise-zurückgebenden Scrollvorgänge unterstützt, sind die Scrollvorgänge zwar immer noch sanft, aber die Toolbar blendet sich nicht aus und dann wieder ein, sobald der Vorgang abgeschlossen ist. Die Funktionserkennung wird von einer Funktion namens supportsScrollPromises() behandelt, die einen Scrollvorgang ausführt und testet, ob dessen Rückgabewert ein Promise ist:

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

Schauen Sie sich den Quellcode an, um zu sehen, wie die Funktionserkennung verwendet wird.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Window.scroll()
• Window.scrollTo()
• Element.scrollBy()
• Window.scrollByLines()
• Window.scrollByPages()