gsap.utils
Quando Usar Este Skill
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, ajustar a uma grade ou normalizar entradas).
Skills relacionados: Use com gsap-core, gsap-timeline e gsap-scrolltrigger ao construir animações; CustomEase e outros utilitários 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ções), em callbacks de ScrollTrigger ou Observer, ou em qualquer JavaScript que conduza GSAP. Todos estão em gsap.utils (ex.: gsap.utils.clamp()).
Omitindo o valor: forma de função. Muitos utilitários aceitam o valor a ser transformado como o último argumento. Se você omitir esse argumento, o utilitário retorna uma função que aceita o valor posteriormente. Use a forma de função quando precisar ajustar, mapear, normalizar ou ajustar vários valores com a mesma configuração (ex.: 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().
// Com valor: retorna o resultado
gsap.utils.clamp(0, 100, 150); // 100
// Sem valor: retorna uma função que você chama com o valor depois
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
Ajuste e Intervalos
clamp(min, max, valor?)
Restringe um valor entre mínimo e máximo. Omita valor para obter uma função: clamp(min, max)(valor).
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, valor?)
Mapeia um valor de um intervalo para outro. Use ao converter posição de scroll, progresso (0–1) ou intervalo de entrada para um intervalo de animação. Omita valor para obter uma função: mapRange(inMin, inMax, outMin, outMax)(valor).
gsap.utils.mapRange(0, 100, 0, 500, 50); // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (progresso para graus)
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, valor?)
Retorna um valor normalizado para 0–1 dentro do intervalo dado. Inverso do mapeamento quando o intervalo alvo é 0–1. Omita valor para obter uma função: normalize(min, max)(valor).
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(início, fim, progresso?)
Interpola entre dois valores em um determinado progresso (0–1). Lida com números, cores e objetos com chaves correspondentes. Omita progresso para obter uma função: interpolate(início, fim)(progresso).
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // cor intermediária
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 Snap
random(mínimo, máximo[, incrementoSnap, retornarFuncao]) / random(array[, retornarFuncao])
Retorna um número aleatório no intervalo mínimo–máximo, ou um elemento aleatório de um array. O incrementoSnap opcional ajusta o resultado para o múltiplo mais próximo (ex.: 5 → múltiplos de 5). Para obter uma função reutilizável, passe true como o último argumento (retornarFuncao); a função retornada não aceita argumentos e retorna um novo valor aleatório a cada vez. Este é o único utilitário que usa true para a forma de função em vez de omitir o valor.
// valor imediato: número no intervalo
gsap.utils.random(-100, 100); // ex.: 42.7
gsap.utils.random(0, 500, 5); // 0–500, ajustado para o múltiplo de 5 mais próximo
// função reutilizável: passe true como último argumento
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // valor aleatório no intervalo, ajustado para 10
randomFn(); // outro valor aleatório
// array: escolhe um valor aleatoriamente
gsap.utils.random(["red", "blue", "green"]); // "red", "blue" ou "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100 ou 200
Forma de string em variáveis de tween: use "random(-100, 100)", "random(-100, 100, 5)" ou "random([0, 100, 200])"; GSAP avalia por alvo.
gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
snap(ajuste, valor?)
Ajusta um valor para o múltiplo mais próximo de ajuste, ou para o valor mais próximo em um array de valores permitidos. Omita valor para obter uma função: snap(ajuste)(valor) (ou snap(arrayAjuste)(valor)).
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 (mais próximo no array)
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
Use em tweens para animação baseada em grade ou etapas:
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
Retorna um novo array com os mesmos elementos em ordem aleatória. Use para randomizar a ordem (ex.: stagger de "random" com uma cópia).
gsap.utils.shuffle([1, 2, 3, 4]); // ex.: [3, 1, 4, 2]
distribute(config)
Retorna uma função que atribui um valor a cada alvo baseado em sua posição no array (ou em uma grade). Usado internamente para staggers avançados; use-o sempre que precisar de valores distribuídos entre muitos elementos (ex.: escala, opacidade, x, atraso). A função retornada recebe (índice, alvo, alvos) — chame-a manualmente ou passe o resultado diretamente para um tween; GSAP a chamará por alvo com índice, elemento e array.
Config (todos opcionais):
| Propriedade | Tipo | Descrição |
|---|---|---|
base | Número | Valor inicial. Padrão 0. |
amount | Número | Total a distribuir entre todos os alvos (adicionado à base). Ex.: amount: 1 com 100 alvos → 0.01 entre cada. Use each em vez disso para definir um passo fixo por alvo. |
each | Número | Quantidade a adicionar entre cada alvo (adicionado à base). Ex.: each: 1 com 4 alvos → 0, 1, 2, 3. Use amount em vez disso para dividir um total. |
from | Número | String | Array | Onde a distribuição começa: índice, ou "start", "center", "edges", "random", "end", ou proporções como [0.25, 0.75]. Padrão 0. |
grid | String | Array | Usar posição de grade em vez de índice plano: [linhas, colunas] (ex.: [5, 10]) ou "auto" para detectar. Omita para array plano. |
axis | String | Para grade: limitar a um eixo ("x" ou "y"). |
ease | Ease | Distribuir valores ao longo de uma curva de easing (ex.: "power1.inOut"). Padrão "none". |
Em um tween: passe o resultado de distribute(config) como o valor da propriedade; GSAP chama a função para cada alvo com (índice, alvo, alvos).
// Escala: elementos do meio 0.5, bordas externas 3 (amount 2.5 distribuído do centro)
gsap.to(".class", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
Uso manual: chame a função retornada com (índice, alvo, alvos) para obter o valor para aquele índice.
const distribuidor = gsap.utils.distribute({
base: 50,
amount: 100,
from: "center",
ease: "power1.inOut"
});
const alvos = gsap.utils.toArray(".box");
const valorParaIndice2 = distribuidor(2, alvos[2], alvos);
Veja distribute() para mais.
Unidades e Parsing
getUnit(valor)
Retorna a string de unidade de um valor (ex.: "px", "%", "deg"). Use ao normalizar ou converter valores.
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // "" (sem unidade)
unitize(valor, unidade)
Anexa uma unidade a um número, ou retorna o valor como está se já tiver uma unidade. Use ao construir valores CSS ou valores finais de tween.
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (inalterado)
splitColor(cor, retornarHSL?)
Converte uma string de cor em um array: [vermelho, verde, azul] (0–255), ou [vermelho, verde, azul, alfa] (4 elementos para RGBA quando alfa está presente ou é necessário). Passe true como o segundo argumento (retornarHSL) para obter [matiz, saturação, luminosidade] ou [matiz, saturação, luminosidade, alfa] (HSL/HSLA) em vez disso. Funciona com "rgb()", "rgba()", "hsl()", "hsla()", hexadecimal e cores nomeadas (ex.: "red"). Use ao animar componentes de cor ou construir gradientes. Veja 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 elementos)
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL: matiz, saturação, luminosidade)
Arrays e Coleções
selector(escopo)
Retorna uma função de seletor com escopo que encontra elementos apenas dentro do elemento (ou ref) dado. Use em componentes para que seletores como ".box" correspondam apenas aos descendentes desse componente, não ao documento inteiro. Aceita um elemento DOM ou uma ref (ex.: React ref; lida com .current).
const q = gsap.utils.selector(containerRef);
q(".box"); // array de elementos .box dentro do container
gsap.to(q(".circle"), { x: 100 });
toArray(valor, escopo?)
Converte um valor para um array: string de seletor (com escopo para elemento), NodeList, HTMLCollection, elemento único ou array. Use ao passar entradas mistas para GSAP (ex.: alvos) e um array verdadeiro é necessário.
gsap.utils.toArray(".item"); // array de elementos
gsap.utils.toArray(".item", container); // com escopo para container
gsap.utils.toArray(nodeList); // [ ... ] a partir de NodeList
pipe(...funções)
Compõe funções: pipe(f1, f2, f3)(valor) retorna f3(f2(f1(valor))). Use ao aplicar uma cadeia de transformações (ex.: normalizar → mapRange → snap) em um tween ou callback.
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // normalizado e então ajustado
wrap(min, max, valor?)
Enrola um valor dentro do intervalo min–max (min inclusive, max exclusive). Use para scroll infinito ou valores cíclicos. Omita valor para obter uma função: wrap(min, max)(valor).
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, valor?)
Enrola valor no intervalo com yoyo (quica nas extremidades). Use para ir e voltar dentro de um intervalo. Omita valor para obter uma função: wrapYoyo(min, max)(valor).
gsap.utils.wrapYoyo(0, 100, 150); // 50 (quica de volta)
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
Melhores práticas
- ✅ Omita o argumento de valor para obter uma função reutilizável quando o mesmo intervalo/config for usado muitas vezes (ex.: manipulador de scroll, callback de tween):
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progresso). - ✅ Use snap para valores alinhados à grade ou baseados em etapas; use toArray quando GSAP ou seu código precisar de um array real a partir de um seletor ou NodeList.
- ✅ Use gsap.utils.selector(escopo) em componentes para que seletores sejam limitados a um container ou ref.
Não Faça
- ❌ Presuma que mapRange / normalize lidam com unidades; eles operam em números. Use getUnit / unitize quando unidades importarem.
- ❌ Sobrescreva ou confie em comportamento não documentado; siga a API documentada.