ScrollTimeline.axis — Eigenschaft · JavaScript-Referenz

Signatur

ScrollTimeline.axis

Beschreibung

Die Eigenschaft axis einer ScrollTimeline gibt an, welche Scrollachse des Quell-Elements (source) den Fortschritt der Zeitleiste bestimmt. Scrollt der Nutzer entlang dieser Achse, läuft eine daran gebundene Animation vorwärts oder rückwärts. Bewegungen entlang der anderen Achse wirken sich nicht aus.

Der Wert wird einmal beim Erzeugen über die Option axis im Konstruktor new ScrollTimeline({ source, axis }) festgelegt und kann danach nur noch gelesen werden. Fehlt die Option, gilt "block".

"block": die Blockachse, also die Richtung, in der Blöcke aufeinander folgen. Bei horizontaler Schreibrichtung ist das die Vertikale.
"inline": die Inline-Achse, also die Laufrichtung des Textes. Bei horizontaler Schreibrichtung ist das die Horizontale.
"y": immer die physische vertikale Achse.
"x": immer die physische horizontale Achse.

Die logischen Werte "block" und "inline" passen sich an writing-mode und direction an. Für mehrsprachige Oberflächen, etwa mit vertikalem japanischem Text, sind sie deshalb meist die robustere Wahl. Die Eigenschaft entspricht der CSS-Eigenschaft animation-timeline: scroll(<scroller> <axis>) bzw. scroll-timeline-axis.

Rückgabewert

Typ

"block" | "inline" | "x" | "y"

Beschreibung

Ein String mit der Scrollachse, die die Zeitleiste antreibt. Standard ist "block".

Beispiele

Standardachse einer ScrollTimeline auslesen

const timeline = new ScrollTimeline({
  source: document.documentElement
});

console.log(timeline.axis);

block

Horizontale Fortschrittsleiste für eine Bildergalerie

// <div id="galerie" style="overflow-x: auto">…</div>
// <div id="fortschritt"></div>
const galerie = document.querySelector('#galerie');
const balken = document.querySelector('#fortschritt');

const timeline = new ScrollTimeline({
  source: galerie,
  axis: 'inline'
});

balken.animate(
  { transform: ['scaleX(0)', 'scaleX(1)'] },
  { timeline, fill: 'both' }
);

console.log(`Zeitleiste folgt der Achse: ${timeline.axis}`);

Zeitleiste folgt der Achse: inline

Mit Feature-Erkennung und Rückfallebene

const erstelleTimeline = (source, axis = 'block') => {
  if (!('ScrollTimeline' in window)) {
    console.warn('ScrollTimeline wird nicht unterstützt – Fallback per scroll-Event nötig.');
    return null;
  }
  return new ScrollTimeline({ source, axis });
};

const tl = erstelleTimeline(document.scrollingElement, 'y');
if (tl) {
  console.log(tl.axis === 'y' ? 'Physisch vertikal' : 'Andere Achse');
}

Physisch vertikal

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie timeline.axis = 'x' hat keine Wirkung und wirft im Strict Mode einen TypeError. Wer eine andere Achse braucht, muss eine neue ScrollTimeline erzeugen.
Ungültige Werte: Wird im Konstruktor ein unbekannter Wert wie 'vertical' übergeben, wirft der Aufruf einen TypeError.
Logische vs. physische Achse: "block" ist nur bei horizontaler Schreibrichtung vertikal. Bei writing-mode: vertical-rl wird "block" horizontal. Wenn die Achse unabhängig vom Layout fest sein soll, sind "x" oder "y" die richtige Wahl.
Kein Scrollüberlauf: Kann das Quell-Element entlang der gewählten Achse nicht scrollen, ist die Zeitleiste inaktiv. currentTime ist dann null.
Browser-Unterstützung: Chromium-Browser ab Version 115 und Safari ab 26. In Firefox ist die API nur hinter dem Flag layout.css.scroll-driven-animations.enabled verfügbar. Prüfe die Unterstützung vorher mit 'ScrollTimeline' in window oder nutze ein Polyfill.

Siehe auch

Element.prototype.animate() ScreenDetailed.availTop ScrollTimeline.source Client.id Accelerometer.x