gsap.utils
Wann du diese Fähigkeit anwenden solltest
Wende sie an, wenn du Code schreibst oder überprüfst, der gsap.utils für Mathematik, Array-/Sammlungsverarbeitung, Einheitenparsen oder Wertezuordnungen in Animationen verwendet (z. B. Scrollen auf einen Wert abbilden, Zufallswerte, Anpassen an ein Raster oder Normalisieren von Eingaben).
Verwandte Fähigkeiten: Verwende sie zusammen mit gsap-core, gsap-timeline und gsap-scrolltrigger beim Erstellen von Animationen; CustomEase und andere Hilfsfunktionen für Beschleunigung findest du in gsap-plugins.
Übersicht
gsap.utils bietet reine Hilfsfunktionen; keine Registrierung erforderlich. Verwende sie in Tween-Variablen (z. B. funktionsbasierte Werte), in ScrollTrigger- oder Observer-Callbacks oder in beliebigem JavaScript, das GSAP steuert. Alle sind unter gsap.utils verfügbar (z. B. gsap.utils.clamp()).
Weglassen des Werts: Funktionsform. Viele Hilfsfunktionen akzeptieren den zu transformierenden Wert als letztes Argument. Wenn du dieses Argument weglässt, gibt die Hilfsfunktion eine Funktion zurück, die den Wert später akzeptiert. Verwende die Funktionsform, wenn du viele Werte mit derselben Konfiguration begrenzen, abbilden, normalisieren oder anpassen musst (z. B. in einem Mausbewegungs-Handler oder Tween-Callback). Ausnahme: random() – übergib true als letztes Argument, um eine wiederverwendbare Funktion zu erhalten (den Wert nicht weglassen); siehe random().
// Mit Wert: gibt das Ergebnis zurück
gsap.utils.clamp(0, 100, 150); // 100
// Ohne Wert: gibt eine Funktion zurück, die du später mit dem Wert aufrufst
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
Begrenzen und Bereiche
clamp(min, max, wert?)
Begrenzt einen Wert zwischen min und max. Lasse wert weg, um eine Funktion zu erhalten: clamp(min, max)(wert).
gsap.utils.clamp(0, 100, 150); // 100
gsap.utils.clamp(0, 100, -10); // 0
let clampFn = gsap.utils.clamp(0, 100);
clampFn(150); // 100
mapRange(inMin, inMax, outMin, outMax, wert?)
Bildet einen Wert von einem Bereich auf einen anderen ab. Verwende es beim Konvertieren der Scrollposition, des Fortschritts (0–1) oder eines Eingabebereichs in einen Animationsbereich. Lasse wert weg, um eine Funktion zu erhalten: mapRange(inMin, inMax, outMin, outMax)(wert).
gsap.utils.mapRange(0, 100, 0, 500, 50); // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (Fortschritt in Grad)
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, wert?)
Gibt einen auf 0–1 normalisierten Wert für den angegebenen Bereich zurück. Umkehrung der Abbildung, wenn der Zielbereich 0–1 ist. Lasse wert weg, um eine Funktion zu erhalten: normalize(min, max)(wert).
gsap.utils.normalize(0, 100, 50); // 0.5
gsap.utils.normalize(100, 300, 200); // 0.5
let normFn = gsap.utils.normalize(0, 100);
normFn(50); // 0.5
interpolate(start, ende, fortschritt?)
Interpoliert zwischen zwei Werten bei einem gegebenen Fortschritt (0–1). Verarbeitet Zahlen, Farben und Objekte mit übereinstimmenden Schlüsseln. Lasse fortschritt weg, um eine Funktion zu erhalten: interpolate(start, ende)(fortschritt).
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mittlere Farbe
gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
let lerp = gsap.utils.interpolate(0, 100);
lerp(0.5); // 50
Zufall und Anpassen (Snap)
random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
Gibt eine Zufallszahl im Bereich minimum–maximum oder ein zufälliges Element aus einem array zurück. Optionales snapIncrement rundet das Ergebnis auf das nächste Vielfache (z. B. 5 → Vielfache von 5). Um eine wiederverwendbare Funktion zu erhalten, übergib true als letztes Argument (returnFunction); die zurückgegebene Funktion benötigt keine Argumente und gibt jedes Mal einen neuen Zufallswert zurück. Dies ist die einzige Hilfsfunktion, die true für die Funktionsform verwendet, anstatt den Wert wegzulassen.
// Sofortiger Wert: Zahl im Bereich
gsap.utils.random(-100, 100); // z. B. 42.7
gsap.utils.random(0, 500, 5); // 0–500, gerundet auf das nächste Vielfache von 5
// Wiederverwendbare Funktion: true als letztes Argument übergeben
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // Zufallswert im Bereich, gerundet auf 10
randomFn(); // ein weiterer Zufallswert
// Array: einen Wert zufällig auswählen
gsap.utils.random(["rot", "blau", "grün"]); // "rot", "blau" oder "grün"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100 oder 200
Zeichenfolgenform in Tween-Variablen: verwende "random(-100, 100)", "random(-100, 100, 5)" oder "random([0, 100, 200])"; GSAP wertet es pro Ziel aus.
gsap.to(".box", { x: "random(-100, 100, 5)", dauer: 1 });
gsap.to(".item", { backgroundColor: "random([rot, blau, grün])" });
snap(snapTo, wert?)
Rundet einen Wert auf das nächste Vielfache von snapTo oder auf den nächsten Wert in einem Array erlaubter Werte. Lasse wert weg, um eine Funktion zu erhalten: snap(snapTo)(wert) (oder snap(snapArray)(wert)).
gsap.utils.snap(10, 23); // 20
gsap.utils.snap(0.25, 0.7); // 0.75
gsap.utils.snap([0, 100, 200], 150); // 100 oder 200 (nächstgelegener im Array)
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
Verwende es in Tweens für raster- oder schrittbasierte Animationen:
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
Gibt ein neues Array mit denselben Elementen in zufälliger Reihenfolge zurück. Verwende es zum Randomisieren der Reihenfolge (z. B. „random“-Stagger mit einer Kopie).
gsap.utils.shuffle([1, 2, 3, 4]); // z. B. [3, 1, 4, 2]
distribute(config)
Gibt eine Funktion zurück, die jedem Ziel einen Wert basierend auf seiner Position im Array (oder in einem Raster) zuweist. Wird intern für erweiterte Stagger verwendet; verwende es immer dann, wenn du Werte auf viele Elemente verteilen musst (z. B. Skalierung, Deckkraft, x, Verzögerung). Die zurückgegebene Funktion erhält (index, ziel, ziele) – rufe sie entweder manuell auf oder übergebe das Ergebnis direkt an einen Tween; GSAP ruft sie pro Ziel mit Index, Element und Array auf.
Config (alle optional):
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
base | Zahl | Startwert. Standard 0. |
amount | Zahl | Gesamtmenge, die auf alle Ziele verteilt wird (zu base addiert). Z. B. amount: 1 mit 100 Zielen → 0,01 zwischen jedem. Verwende stattdessen each, um einen festen Schritt pro Ziel festzulegen. |
each | Zahl | Betrag, der zwischen jedem Ziel hinzugefügt wird (zu base addiert). Z. B. each: 1 mit 4 Zielen → 0, 1, 2, 3. Verwende stattdessen amount, um eine Gesamtsumme aufzuteilen. |
from | Zahl | Zeichenfolge | Array | Wo die Verteilung beginnt: Index oder "start", "center", "edges", "random", "end" oder Verhältnisse wie [0.25, 0.75]. Standard 0. |
grid | Zeichenfolge | Array | Verwende die Rasterposition anstelle des flachen Index: [zeilen, spalten] (z. B. [5, 10]) oder "auto" zur Erkennung. Für flaches Array weglassen. |
axis | Zeichenfolge | Für Raster: auf eine Achse beschränken ("x" oder "y"). |
ease | Ease | Verteile Werte entlang einer Beschleunigungskurve (z. B. "power1.inOut"). Standard "none". |
In einem Tween: übergib das Ergebnis von distribute(config) als Eigenschaftswert; GSAP ruft die Funktion für jedes Ziel mit (index, ziel, ziele) auf.
// Skalierung: mittlere Elemente 0,5, äußere Kanten 3 (Menge 2,5 von der Mitte verteilt)
gsap.to(".class", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
Manuelle Verwendung: rufe die zurückgegebene Funktion mit (index, ziel, ziele) auf, um den Wert für diesen Index zu erhalten.
const distributor = gsap.utils.distribute({
base: 50,
amount: 100,
from: "center",
ease: "power1.inOut"
});
const ziele = gsap.utils.toArray(".box");
const wertFuerIndex2 = distributor(2, ziele[2], ziele);
Siehe distribute() für weitere Informationen.
Einheiten und Parsen
getUnit(wert)
Gibt die Einheitenzeichenfolge eines Werts zurück (z. B. "px", "%", "deg"). Verwende es beim Normalisieren oder Konvertieren von Werten.
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // "" (ohne Einheit)
unitize(wert, einheit)
Fügt einem Wert eine Einheit hinzu oder gibt den Wert unverändert zurück, wenn er bereits eine Einheit hat. Verwende es beim Erstellen von CSS-Werten oder Tween-Endwerten.
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (unverändert)
splitColor(farbe, returnHSL?)
Konvertiert eine Farbzeichenfolge in ein Array: [rot, grün, blau] (0–255) oder [rot, grün, blau, alpha] (4 Elemente für RGBA, wenn Alpha vorhanden oder erforderlich ist). Übergib true als zweites Argument (returnHSL), um stattdessen [farbton, sättigung, helligkeit] oder [farbton, sättigung, helligkeit, alpha] (HSL/HSLA) zu erhalten. Funktioniert mit "rgb()", "rgba()", "hsl()", "hsla()", Hex- und benannten Farben (z. B. "rot"). Verwende es beim Animieren von Farbkomponenten oder Erstellen von Farbverläufen. Siehe splitColor().
gsap.utils.splitColor("rot"); // [255, 0, 0]
gsap.utils.splitColor("#6fb936"); // [111, 185, 54]
gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5] (4 Elemente)
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL: Farbton, Sättigung, Helligkeit)
Arrays und Sammlungen
selector(bereich)
Gibt eine bereichsbezogene Selektorfunktion zurück, die Elemente nur innerhalb des angegebenen Elements (oder Referenz) findet. Verwende es in Komponenten, sodass Selektoren wie ".box" nur Nachkommen dieser Komponente und nicht das gesamte Dokument abgleichen. Akzeptiert ein DOM-Element oder eine Referenz (z. B. React-Ref; behandelt .current).
const q = gsap.utils.selector(containerRef);
q(".box"); // Array von .box-Elementen innerhalb des Containers
gsap.to(q(".circle"), { x: 100 });
toArray(wert, bereich?)
Konvertiert einen Wert in ein Array: Selektorenzeichenfolge (auf Element bezogen), NodeList, HTMLCollection, einzelnes Element oder Array. Verwende es, wenn du gemischte Eingaben an GSAP übergibst (z. B. Ziele) und ein echtes Array benötigt wird.
gsap.utils.toArray(".item"); // Array von Elementen
gsap.utils.toArray(".item", container); // auf Container bezogen
gsap.utils.toArray(nodeList); // [ ... ] aus NodeList
pipe(...funktionen)
Komponiert Funktionen: pipe(f1, f2, f3)(wert) gibt f3(f2(f1(wert))) zurück. Verwende es, wenn eine Kette von Transformationen angewendet wird (z. B. normalisieren → mapRange → snap) in einem Tween oder Callback.
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // normalisiert und dann gerundet
wrap(min, max, wert?)
Wickelt einen Wert in den Bereich min–max (min inklusive, max exklusiv). Verwende es für Endlos-Scrollen oder zyklische Werte. Lasse wert weg, um eine Funktion zu erhalten: wrap(min, max)(wert).
gsap.utils.wrap(0, 360, 370); // 10
gsap.utils.wrap(0, 360, -10); // 350
let wrapFn = gsap.utils.wrap(0, 360);
wrapFn(370); // 10
wrapYoyo(min, max, wert?)
Wickelt den Wert im Bereich mit einem Yoyo (prallt an den Enden zurück). Verwende es für Hin-und-Her innerhalb eines Bereichs. Lasse wert weg, um eine Funktion zu erhalten: wrapYoyo(min, max)(wert).
gsap.utils.wrapYoyo(0, 100, 150); // 50 (prallt zurück)
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
Best Practices
- ✅ Lasse das Wert-Argument weg, um eine wiederverwendbare Funktion zu erhalten, wenn derselbe Bereich/dieselbe Konfiguration mehrfach verwendet wird (z. B. Scroll-Handler, Tween-Callback):
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(fortschritt). - ✅ Verwende snap für rasterausgerichtete oder schrittbasierte Werte; verwende toArray, wenn GSAP oder dein Code ein echtes Array aus einem Selektor oder einer NodeList benötigt.
- ✅ Verwende gsap.utils.selector(bereich) in Komponenten, sodass Selektoren auf einen Container oder eine Referenz beschränkt sind.
Nicht tun
- ❌ Gehe nicht davon aus, dass mapRange / normalize Einheiten verarbeiten; sie arbeiten mit Zahlen. Verwende getUnit / unitize, wenn Einheiten eine Rolle spielen.
- ❌ Überschreibe oder verlasse dich nicht auf undokumentiertes Verhalten; halte dich an die dokumentierte API.