gsap.utils
Quand utiliser ce skill
À appliquer lors de l'écriture ou de la révision de code qui utilise gsap.utils pour les mathématiques, la manipulation de tableaux/collections, l'analyse d'unités ou le mappage de valeurs dans les animations (par exemple, mapper le défilement à une valeur, randomiser, accrocher à une grille ou normaliser des entrées).
Skills connexes : À utiliser avec gsap-core, gsap-timeline et gsap-scrolltrigger lors de la création d'animations ; CustomEase et autres utilitaires d'assouplissement se trouvent dans gsap-plugins.
Présentation
gsap.utils fournit des fonctions d'aide pures ; aucune inscription n'est nécessaire. Utilisez-les dans les variables de tween (par exemple, les valeurs basées sur des fonctions), dans les rappels ScrollTrigger ou Observer, ou dans tout code JavaScript qui pilote GSAP. Toutes sont accessibles via gsap.utils (par exemple gsap.utils.clamp()).
Omettre la valeur : forme fonctionnelle. De nombreux utilitaires acceptent la valeur à transformer comme dernier argument. Si vous omettez cet argument, l'utilitaire renvoie une fonction qui acceptera la valeur plus tard. Utilisez la forme fonctionnelle lorsque vous devez clamper, mapper, normaliser ou accrocher plusieurs valeurs avec la même configuration (par exemple, dans un gestionnaire mousemove ou un rappel de tween). Exception : random() — passez true comme dernier argument pour obtenir une fonction réutilisable (n'omettez pas la valeur) ; voir random().
// Avec valeur : renvoie le résultat
gsap.utils.clamp(0, 100, 150); // 100
// Sans valeur : renvoie une fonction que vous appelez avec la valeur plus tard
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
Clamp et plages
clamp(min, max, value?)
Contraint une valeur entre min et max. Omettez value pour obtenir une fonction : clamp(min, max)(value).
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, value?)
Mappe une valeur d'une plage à une autre. Utilisez-le lors de la conversion de la position de défilement, de la progression (0–1) ou d'une plage d'entrée vers une plage d'animation. Omettez value pour obtenir une fonction : mapRange(inMin, inMax, outMin, outMax)(value).
gsap.utils.mapRange(0, 100, 0, 500, 50); // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (progression en degrés)
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, value?)
Renvoie une valeur normalisée entre 0 et 1 pour la plage donnée. Inverse du mappage lorsque la plage cible est 0–1. Omettez value pour obtenir une fonction : normalize(min, max)(value).
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, end, progress?)
Interpole entre deux valeurs à une progression donnée (0–1). Gère les nombres, les couleurs et les objets avec des clés correspondantes. Omettez progress pour obtenir une fonction : interpolate(start, end)(progress).
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // couleur intermédiaire
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
Random et Snap
random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
Renvoie un nombre aléatoire dans la plage minimum–maximum, ou un élément aléatoire d'un tableau. Le paramètre optionnel snapIncrement accroche le résultat au multiple le plus proche (par exemple 5 → multiples de 5). Pour obtenir une fonction réutilisable, passez true comme dernier argument (returnFunction) ; la fonction renvoyée ne prend aucun argument et renvoie une nouvelle valeur aléatoire à chaque appel. C'est le seul utilitaire qui utilise true pour la forme fonctionnelle au lieu d'omettre la valeur.
// valeur immédiate : nombre dans la plage
gsap.utils.random(-100, 100); // par exemple 42.7
gsap.utils.random(0, 500, 5); // 0–500, accroché au 5 le plus proche
// fonction réutilisable : passez true comme dernier argument
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // valeur aléatoire dans la plage, accrochée à 10
randomFn(); // une autre valeur aléatoire
// tableau : choisir une valeur au hasard
gsap.utils.random(["red", "blue", "green"]); // "red", "blue" ou "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100 ou 200
Forme chaîne dans les variables de tween : utilisez "random(-100, 100)", "random(-100, 100, 5)" ou "random([0, 100, 200])" ; GSAP l'évalue par cible.
gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
snap(snapTo, value?)
Accroche une valeur au multiple le plus proche de snapTo, ou à la valeur la plus proche dans un tableau de valeurs autorisées. Omettez value pour obtenir une fonction : snap(snapTo)(value) (ou snap(snapArray)(value)).
gsap.utils.snap(10, 23); // 20
gsap.utils.snap(0.25, 0.7); // 0.75
gsap.utils.snap([0, 100, 200], 150); // 100 ou 200 (le plus proche dans le tableau)
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
Utilisez dans les tweens pour une animation basée sur une grille ou par étapes :
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
Renvoie un nouveau tableau avec les mêmes éléments dans un ordre aléatoire. Utilisez pour randomiser l'ordre (par exemple, stagger à partir de "random" avec une copie).
gsap.utils.shuffle([1, 2, 3, 4]); // par exemple [3, 1, 4, 2]
distribute(config)
Renvoie une fonction qui attribue une valeur à chaque cible en fonction de sa position dans le tableau (ou dans une grille). Utilisé en interne pour les staggers avancés ; utilisez-le chaque fois que vous avez besoin de répartir des valeurs sur de nombreux éléments (par exemple, scale, opacity, x, delay). La fonction renvoyée reçoit (index, target, targets) — appelez-la manuellement ou passez le résultat directement dans un tween ; GSAP l'appellera par cible avec index, élément et tableau.
Config (tous optionnels) :
| Propriété | Type | Description |
|---|---|---|
base | Number | Valeur de départ. Par défaut 0. |
amount | Number | Total à distribuer sur toutes les cibles (ajouté à base). Par exemple amount: 1 avec 100 cibles → 0.01 entre chaque. Utilisez each à la place pour définir un pas fixe par cible. |
each | Number | Quantité à ajouter entre chaque cible (ajoutée à base). Par exemple each: 1 avec 4 cibles → 0, 1, 2, 3. Utilisez amount à la place pour diviser un total. |
from | Number | String | Array | Où la distribution commence : index, ou "start", "center", "edges", "random", "end", ou des ratios comme [0.25, 0.75]. Par défaut 0. |
grid | String | Array | Utilise la position dans la grille au lieu de l'index plat : [rows, columns] (par exemple [5, 10]) ou "auto" pour détecter. Omettez pour un tableau plat. |
axis | String | Pour la grille : limite à un axe ("x" ou "y"). |
ease | Ease | Distribue les valeurs le long d'une courbe d'assouplissement (par exemple "power1.inOut"). Par défaut "none". |
Dans un tween : passez le résultat de distribute(config) comme valeur de propriété ; GSAP appelle la fonction pour chaque cible avec (index, target, targets).
// Scale : éléments du milieu 0.5, bords extérieurs 3 (amount 2.5 distribué depuis le centre)
gsap.to(".class", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
Utilisation manuelle : appelez la fonction renvoyée avec (index, target, targets) pour obtenir la valeur pour cet index.
const distributor = gsap.utils.distribute({
base: 50,
amount: 100,
from: "center",
ease: "power1.inOut"
});
const targets = gsap.utils.toArray(".box");
const valueForIndex2 = distributor(2, targets[2], targets);
Voir distribute() pour plus d'informations.
Unités et analyse
getUnit(value)
Renvoie la chaîne de caractères de l'unité d'une valeur (par exemple "px", "%", "deg"). Utilisez-le lors de la normalisation ou de la conversion de valeurs.
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // "" (sans unité)
unitize(value, unit)
Ajoute une unité à un nombre, ou renvoie la valeur telle quelle si elle a déjà une unité. Utilisez-le lors de la construction de valeurs CSS ou de valeurs finales de tween.
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (inchangé)
splitColor(color, returnHSL?)
Convertit une chaîne de couleur en un tableau : [red, green, blue] (0–255), ou [red, green, blue, alpha] (4 éléments pour RGBA lorsque alpha est présent ou nécessaire). Passez true comme second argument (returnHSL) pour obtenir [hue, saturation, lightness] ou [hue, saturation, lightness, alpha] (HSL/HSLA) à la place. Fonctionne avec "rgb()", "rgba()", "hsl()", "hsla()", hex et les couleurs nommées (par exemple "red"). Utilisez-le lors de l'animation de composantes de couleur ou de la construction de dégradés. Voir splitColor().
gsap.utils.splitColor("red"); // [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 éléments)
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL : hue, saturation, lightness)
Tableaux et collections
selector(scope)
Renvoie une fonction de sélection délimitée qui trouve les éléments uniquement dans l'élément (ou la référence) donné. Utilisez-la dans les composants pour que les sélecteurs comme ".box" correspondent uniquement aux descendants de ce composant, et non à l'ensemble du document. Accepte un élément DOM ou une référence (par exemple une référence React ; gère .current).
const q = gsap.utils.selector(containerRef);
q(".box"); // tableau d'éléments .box à l'intérieur du conteneur
gsap.to(q(".circle"), { x: 100 });
toArray(value, scope?)
Convertit une valeur en tableau : chaîne de sélecteur (délimitée à un élément), NodeList, HTMLCollection, élément unique ou tableau. Utilisez-la lors du passage d'entrées mixtes à GSAP (par exemple, cibles) lorsqu'un véritable tableau est nécessaire.
gsap.utils.toArray(".item"); // tableau d'éléments
gsap.utils.toArray(".item", container); // délimité au conteneur
gsap.utils.toArray(nodeList); // [ ... ] à partir d'un NodeList
pipe(...functions)
Compose des fonctions : pipe(f1, f2, f3)(value) renvoie f3(f2(f1(value))). Utilisez-le lors de l'application d'une chaîne de transformations (par exemple normaliser → mapRange → snap) dans un tween ou un rappel.
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // normalisé puis accroché
wrap(min, max, value?)
Enroule une valeur dans la plage min–max (min inclus, max exclus). Utilisez-le pour le défilement infini ou les valeurs cycliques. Omettez value pour obtenir une fonction : wrap(min, max)(value).
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, value?)
Enroule une valeur dans la plage avec un effet yoyo (rebondit aux extrémités). Utilisez-le pour les allers-retours dans une plage. Omettez value pour obtenir une fonction : wrapYoyo(min, max)(value).
gsap.utils.wrapYoyo(0, 100, 150); // 50 (rebondit)
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
Bonnes pratiques
- ✅ Omettez l'argument valeur pour obtenir une fonction réutilisable lorsque la même plage/config est utilisée plusieurs fois (par exemple, gestionnaire de défilement, rappel de tween) :
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress). - ✅ Utilisez snap pour les valeurs alignées sur une grille ou par étapes ; utilisez toArray lorsque GSAP ou votre code a besoin d'un véritable tableau à partir d'un sélecteur ou d'un NodeList.
- ✅ Utilisez gsap.utils.selector(scope) dans les composants pour que les sélecteurs soient délimités à un conteneur ou une référence.
À ne pas faire
- ❌ Ne supposez pas que mapRange / normalize gèrent les unités ; ils travaillent sur des nombres. Utilisez getUnit / unitize lorsque les unités sont importantes.
- ❌ Ne remplacez pas et ne vous fiez pas à un comportement non documenté ; respectez l'API documentée.