본문으로 건너뛰기

시작하기

Glaze과 사용할 애니메이션 엔진을 설치하세요:

셸
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion

GSAP과 Motion은 선택적 피어 종속성입니다. Glaze은 두 엔진을 모두 포함하지 않습니다.

한 번 초기화

요소가 DOM에 들어간 뒤 glaze()을 호출하세요. 엔진과 모든 구성을 한 번의 호출로 전달합니다:

TypeScript
import glaze from "glazejs"
import { gsap } from "gsap"

const root = document.querySelector("#app")
if (!root) throw new Error("Missing application root")

const animations = glaze({
  lib: { gsap: { core: gsap } },
  element: root,
  breakpoints: { md: "(min-width: 768px)" },
  defaults: { element: "duration-0.6" },
  presets: { rise: "from:opacity-0|y-24" },
  watch: { debounceTime: 200 },
})
HTML
<div id="app">
  <div data-animate="preset-rise"></div>
  <div data-animate="@md:preset-rise from:duration-1"></div>
</div>

이 호출은 루트를 스캔하고 해당 루트의 애니메이션을 만듭니다. glaze()을 다시 호출하면 새 인스턴스가 생성되며 기존 인스턴스에 구성이 추가되지 않습니다.

명시적 어댑터 API은 GSAP과 동일합니다:

TypeScript
import glaze from "glazejs"
import { createGsapAdapter } from "glazejs/gsap"
import { gsap } from "gsap"

const animations = glaze({ adapter: createGsapAdapter(gsap) })

Motion에는 glazejs/motion의 createMotionAdapter({ animate, stagger })을 사용하세요. 설정과 지원 기능은 Motion 가이드를 참조하세요. 하나의 구성에서 adapter 또는 lib 중 하나를 선택하세요.

옵션

옵션 기본값 용도
lib.gsap.core 없음 원래 설정을 위한 GSAP 인스턴스 API.
adapter 없음 명시적 GSAP 또는 Motion 어댑터. lib의 대안입니다.
element document 스캔하고 관찰할 DOM 루트.
dataAttribute "data-animate" 애니메이션 유틸리티가 들어 있는 속성.
className 없음 클래스 구문을 위한 클래스 접두사.
breakpoints { default: "(min-width: 1px)" } 이름이 지정된 미디어 쿼리.
defaults.tl 없음 기본 타임라인 설정.
defaults.element 없음 기본 애니메이션 속성. 요소 유틸리티가 우선합니다.
presets 없음 이름이 지정된 재사용 가능 애니메이션 문자열.
watch false DOM 변경을 관찰합니다. true은 500ms 디바운스를 사용하거나 { debounceTime }을 전달합니다.

감시 모드는 루트 내의 하위 요소 추가 및 제거와 애니메이션 속성 변경을 감지합니다. 클래스 모드에서는 클래스 변경도 감지합니다. 관련 DOM 변경이 발생하면 디바운스된 재구성을 예약합니다. 인라인 애니메이션 스타일 변경은 재구성을 유발하지 않습니다.

새로 고침 및 정리

수명 주기 관리를 위해 반환된 인스턴스를 보관하세요:

TypeScript
// Rescan after rendering new elements when watch is disabled.
animations.refresh()

// On component unmount or page teardown:
animations.destroy()

refresh()은 원래 설정을 사용해 다시 빌드합니다. destroy()은 애니메이션을 중지하고, 옵저버와 미디어 쿼리 리스너를 제거하며, 원래 인라인 스타일을 복원합니다. 여러 번 호출해도 안전합니다. 파괴된 인스턴스는 refresh()로 다시 시작할 수 없습니다. 다시 마운트할 때는 새 인스턴스를 만드세요.

반환값에는 timelines, breakpoints 및 확인된 state도 포함됩니다. 각 타임라인 항목에는 해당 엔진의 타임라인, ID, 미디어 쿼리, 루트 요소, 설정 및 애니메이션이 적용된 요소가 기록됩니다. 인스턴스를 만든 어댑터를 알고 있는 코드에서 해당 엔진 전용 재생 호출을 사용하세요.

새로 고침과 반응형 재빌드 과정에서 네이티브 타임라인 객체가 교체될 수 있습니다. 재빌드 후 재생을 제어하려면 이전 네이티브 타임라인 참조를 유지하는 대신 현재 timelines[index].timeline을 읽으세요.

CDN

공개 진입점은 ES 모듈이며 ESM CDN에서도 불러올 수 있습니다:

JavaScript
import glaze from "https://esm.sh/glazejs"
import { gsap } from "https://esm.sh/gsap@3.15.0"

const animations = glaze({ lib: { gsap: { core: gsap } } })