gsap.utils

Selecionado das habilidades oficiais do GSAP da GreenSock: https://github.com/greensock/gsap-skills

Quando Usar Esta Habilidade

Aplique ao escrever ou revisar código que usa gsap.utils para matemática, manipulação de arrays/coleções, análise de unidades ou mapeamento de valores em animações (por exemplo, mapear scroll para um valor, randomizar, "travar" em uma grade ou normalizar entradas).

Habilidades relacionadas: Use com gsap-core, gsap-timeline e gsap-scrolltrigger ao construir animações; CustomEase e outras utilidades de easing estão em gsap-plugins.

Visão Geral

gsap.utils fornece ajudantes puros; não é necessário registrar. Use em variáveis de tween (por exemplo, valores baseados em função), em callbacks de ScrollTrigger ou Observer, ou em qualquer JS que controle o GSAP. Todos estão em gsap.utils (por exemplo, gsap.utils.clamp()).

Omitindo o valor: forma de função. Muitos utils aceitam o valor a ser transformado como o último argumento. Se você omitir esse argumento, o util retorna uma função que aceita o valor posteriormente. Use a forma de função quando precisar limitar, mapear, normalizar ou "travar" muitos valores com a mesma configuração (por exemplo, em um manipulador de mousemove ou callback de tween). Exceção: random() — passe true como o último argumento para obter uma função reutilizável (não omita o valor); veja random().

// With value: returns the result
gsap.utils.clamp(0, 100, 150); // 100

// Without value: returns a function you call with the value later
let c = gsap.utils.clamp(0, 100);
c(150);  // 100
c(-10);  // 0

Limitação e Faixas

clamp(min, max, value?)

Limita um valor entre min e max. Omita value para obter uma função: 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?)

Mapeia um valor de uma faixa para outra. Use ao converter posição de scroll, progresso (0–1) ou faixa de entrada para uma faixa de animação. Omita value para obter uma função: 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 (progress to degrees)

let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50);  // 250

normalize(min, max, value?)

Retorna um valor normalizado para 0–1 para a faixa dada. Inverso de mapear quando a faixa de destino é 0–1. Omita value para obter uma função: 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?)

Interpola entre dois valores em um progresso dado (0–1). Lida com números, cores e objetos com chaves correspondentes. Omita progress para obter uma função: interpolate(start, end)(progress).

gsap.utils.interpolate(0, 100, 0.5);       // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color
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

Aleatório e Travar

random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])

Retorna um número aleatório na faixa minimum–maximum, ou um elemento aleatório de um array. snapIncrement opcional "trava" o resultado no múltiplo mais próximo (por exemplo, 5 → múltiplos de 5). Para obter uma função reutilizável, passe true como o último argumento (returnFunction); a função retornada não aceita argumentos e retorna um novo valor aleatório a cada vez. Este é o único util que usa true para a forma de função em vez de omitir o valor.

// immediate value: number in range
gsap.utils.random(-100, 100);        // e.g. 42.7
gsap.utils.random(0, 500, 5);        // 0–500, snapped to nearest 5

// reusable function: pass true as last argument
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn();  // random value in range, snapped to 10
randomFn();  // another random value

// array: pick one value at random
gsap.utils.random(["red", "blue", "green"]);  // "red", "blue", or "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray();  // 0, 100, or 200

…