gsap.utils
이 스킬을 사용해야 하는 경우
gsap.utils를 사용하여 애니메이션에서 수학 연산, 배열/컬렉션 처리, 단위 파싱, 값 매핑(예: 스크롤을 값에 매핑, 랜덤화, 그리드에 스냅, 입력 정규화)을 하는 코드를 작성하거나 검토할 때 적용하세요.
관련 스킬: 애니메이션을 만들 때 gsap-core, gsap-timeline, gsap-scrolltrigger와 함께 사용하세요. CustomEase 및 기타 이징 유틸리티는 gsap-plugins에 있습니다.
개요
gsap.utils는 순수 헬퍼 함수를 제공하며, 등록이 필요 없습니다. 트윈 변수(예: 함수 기반 값), ScrollTrigger 또는 Observer 콜백, GSAP를 구동하는 모든 JS에서 사용할 수 있습니다. 모든 함수는 gsap.utils에서 접근 가능합니다(예: gsap.utils.clamp()).
값 생략: 함수 형태. 많은 유틸리티는 변환할 값을 마지막 인자로 받습니다. 이 인자를 생략하면 나중에 값을 받는 함수를 반환합니다. 동일한 설정으로 여러 값을 clamp, map, normalize, snap해야 할 때(예: mousemove 핸들러나 트윈 콜백) 함수 형태를 사용하세요. 예외: random() — 재사용 가능한 함수를 얻으려면 마지막 인자로 true를 전달하세요(값을 생략하지 않음). 자세한 내용은 random()을 참조하세요.
// 값 포함: 결과 직접 반환
gsap.utils.clamp(0, 100, 150); // 100
// 값 생략: 나중에 값으로 호출할 함수 반환
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
제한 및 범위
clamp(min, max, value?)
값을 최소값과 최대값 사이로 제한합니다. value를 생략하면 함수를 반환합니다: 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?)
값을 한 범위에서 다른 범위로 매핑합니다. 스크롤 위치, 진행률(0–1) 또는 입력 범위를 애니메이션 범위로 변환할 때 사용하세요. value를 생략하면 함수를 반환합니다: 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 (진행률을 각도로)
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, value?)
주어진 범위에 대해 0–1로 정규화된 값을 반환합니다. 대상 범위가 0–1일 때 매핑의 역함수입니다. value를 생략하면 함수를 반환합니다: 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?)
주어진 진행률(0–1)에서 두 값 사이를 보간합니다. 숫자, 색상, 일치하는 키를 가진 객체를 처리합니다. progress를 생략하면 함수를 반환합니다: interpolate(start, end)(progress).
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // 중간 색상
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(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
minimum–maximum 범위의 랜덤 숫자 또는 배열의 랜덤 요소를 반환합니다. 선택적 snapIncrement는 결과를 가장 가까운 배수로 스냅합니다(예: 5 → 5의 배수). 재사용 가능한 함수를 얻으려면 마지막 인자로 true(returnFunction)를 전달하세요. 반환된 함수는 인자를 받지 않고 호출할 때마다 새로운 랜덤 값을 반환합니다. 값 생략 대신 함수 형태를 위해 true를 사용하는 유일한 유틸리티입니다.
// 즉시 값: 범위 내 숫자
gsap.utils.random(-100, 100); // 예: 42.7
gsap.utils.random(0, 500, 5); // 0–500, 가장 가까운 5로 스냅
// 재사용 가능한 함수: 마지막 인자로 true 전달
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // 범위 내 랜덤 값, 10 단위로 스냅
randomFn(); // 또 다른 랜덤 값
// 배열: 무작위로 하나의 값 선택
gsap.utils.random(["red", "blue", "green"]); // "red", "blue", 또는 "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100, 또는 200
트윈 변수에서 문자열 형태: "random(-100, 100)", "random(-100, 100, 5)" 또는 "random([0, 100, 200])"을 사용하세요. GSAP이 대상별로 평가합니다.
gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
snap(snapTo, value?)
값을 snapTo의 가장 가까운 배수 또는 허용된 값 배열에서 가장 가까운 값으로 스냅합니다. value를 생략하면 함수를 반환합니다: snap(snapTo)(value) (또는 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 또는 200 (배열에서 가장 가까운 값)
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
트윈에서 그리드 또는 단계 기반 애니메이션에 사용:
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
동일한 요소를 무작위 순서로 가진 새 배열을 반환합니다. 순서를 무작위화할 때 사용하세요(예: 복사본과 함께 "random"부터 스태거).
gsap.utils.shuffle([1, 2, 3, 4]); // 예: [3, 1, 4, 2]
distribute(config)
함수를 반환하며, 배열(또는 그리드) 내 위치에 따라 각 대상에 값을 할당합니다. 고급 스태거링을 위해 내부적으로 사용됩니다. 여러 요소에 값을 분산해야 할 때 사용하세요(예: scale, opacity, x, delay). 반환된 함수는 (index, target, targets)를 받습니다. 수동으로 호출하거나 결과를 직접 트윈에 전달하면 GSAP이 대상별로 index, element, array와 함께 호출합니다.
설정(모두 선택 사항):
| 속성 | 유형 | 설명 |
|---|---|---|
base | Number | 시작 값. 기본값 0. |
amount | Number | 모든 대상에 분산할 총량(base에 추가됨). 예: 100개의 대상에 amount: 1 → 대상 간 0.01. 대상별 고정 단계를 설정하려면 대신 each를 사용하세요. |
each | Number | 각 대상 사이에 추가할 양(base에 추가됨). 예: 4개의 대상에 each: 1 → 0, 1, 2, 3. 총량을 분할하려면 대신 amount를 사용하세요. |
from | Number | String | Array | 분포 시작 위치: 인덱스 또는 "start", "center", "edges", "random", "end" 또는 비율(예: [0.25, 0.75]). 기본값 0. |
grid | String | Array | 평면 인덱스 대신 그리드 위치 사용: [rows, columns](예: [5, 10]) 또는 감지를 위해 "auto". 평면 배열의 경우 생략. |
axis | String | 그리드의 경우: 하나의 축으로 제한("x" 또는 "y"). |
ease | Ease | 이즈 곡선을 따라 값 분포(예: "power1.inOut"). 기본값 "none". |
트윈 내에서: distribute(config)의 결과를 속성 값으로 전달하면 GSAP이 각 대상에 대해 (index, target, targets)로 함수를 호출합니다.
// Scale: 중간 요소 0.5, 바깥쪽 가장자리 3 (중앙에서 amount 2.5 분산)
gsap.to(".class", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
수동 사용: 반환된 함수를 (index, target, targets)로 호출하여 해당 인덱스의 값을 얻습니다.
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);
더 많은 정보는 distribute()를 참조하세요.
단위 및 파싱
getUnit(value)
값의 단위 문자열을 반환합니다(예: "px", "%", "deg"). 값을 정규화하거나 변환할 때 사용하세요.
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // "" (단위 없음)
unitize(value, unit)
숫자에 단위를 추가하거나, 값에 이미 단위가 있으면 그대로 반환합니다. CSS 값이나 트윈 종료 값을 만들 때 사용하세요.
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (변경 없음)
splitColor(color, returnHSL?)
색상 문자열을 배열로 변환합니다: [red, green, blue] (0–255) 또는 (알파가 있거나 필요한 경우) [red, green, blue, alpha] (RGBA의 경우 4개 요소). 두 번째 인자로 true(returnHSL)를 전달하면 [hue, saturation, lightness] 또는 [hue, saturation, lightness, alpha] (HSL/HSLA)를 대신 반환합니다. "rgb()", "rgba()", "hsl()", "hsla()", 16진수 및 명명된 색상(예: "red")과 함께 작동합니다. 색상 구성 요소를 애니메이션하거나 그라데이션을 만들 때 사용하세요. 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개 요소)
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL: hue, saturation, lightness)
배열 및 컬렉션
selector(scope)
주어진 요소(또는 ref) 내에서만 요소를 찾는 범위가 지정된 선택자 함수를 반환합니다. 컴포넌트에서 ".box"와 같은 선택자가 전체 문서가 아닌 해당 컴포넌트의 하위 요소만 일치하도록 사용하세요. DOM 요소 또는 ref(예: React ref; .current 처리)를 허용합니다.
const q = gsap.utils.selector(containerRef);
q(".box"); // 컨테이너 내 .box 요소 배열
gsap.to(q(".circle"), { x: 100 });
toArray(value, scope?)
값을 배열로 변환합니다: 선택자 문자열(요소로 범위 지정), NodeList, HTMLCollection, 단일 요소 또는 배열. 혼합 입력을 GSAP에 전달할 때(예: targets) 실제 배열이 필요할 때 사용하세요.
gsap.utils.toArray(".item"); // 요소 배열
gsap.utils.toArray(".item", container); // 컨테이너로 범위 지정
gsap.utils.toArray(nodeList); // NodeList에서 [ ... ]
pipe(...functions)
함수를 합성합니다: **pipe(f1, f2, f3)(value)**는 f3(f2(f1(value)))를 반환합니다. 트윈 또는 콜백에서 변환 체인(예: normalize → mapRange → snap)을 적용할 때 사용하세요.
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // 정규화 후 스냅
wrap(min, max, value?)
값을 min–max 범위로 감쌉니다(min 포함, max 제외). 무한 스크롤 또는 순환 값에 사용하세요. value를 생략하면 함수를 반환합니다: 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?)
요요 효과(끝에서 튕김)로 범위 내에서 값을 감쌉니다. 범위 내에서 앞뒤로 움직일 때 사용하세요. value를 생략하면 함수를 반환합니다: wrapYoyo(min, max)(value).
gsap.utils.wrapYoyo(0, 100, 150); // 50 (튕겨서 돌아옴)
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
모범 사례
- ✅ 동일한 범위/구성이 여러 번 사용될 때(예: 스크롤 핸들러, 트윈 콜백) 재사용 가능한 함수를 얻으려면 값 인자를 생략하세요:
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress). - ✅ 그리드 정렬 또는 단계 기반 값에는 snap을 사용하세요. GSAP 또는 코드가 선택자나 NodeList에서 실제 배열이 필요할 때 toArray를 사용하세요.
- ✅ 컴포넌트에서 **gsap.utils.selector(scope)**를 사용하여 선택자가 컨테이너나 ref로 범위가 지정되도록 하세요.
금지 사항
- ❌ mapRange / normalize가 단위를 처리한다고 가정하지 마세요. 숫자로만 작동합니다. 단위가 중요할 때는 getUnit / unitize를 사용하세요.
- ❌ 문서화되지 않은 동작을 재정의하거나 의존하지 마세요. 문서화된 API를 따르세요.