이징 함수

stable

모션 가속/감속을 정의하는 이징 함수 컬렉션과 유틸리티

@hua-labs/motion-corev2.0.0

Import

import {
  linear,
  easeIn,
  easeOut,
  easeInOut,
  easeInQuad,
  easeOutQuad,
  easeInOutQuad,
  getEasing,
  applyEasing,
  safeApplyEasing,
  isValidEasing,
  easing,
  easingPresets,
} from '@hua-labs/motion-core'

타입

type EasingFunction = (t: number) => number

type EasingType =
  | 'linear'
  | 'easeIn' | 'easeOut' | 'easeInOut'
  | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad'
  | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic'
  | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart'
  | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint'
  | 'easeInSine' | 'easeOutSine' | 'easeInOutSine'
  | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo'
  | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc'
  | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce'
  | 'easeInBack' | 'easeOutBack' | 'easeInOutBack'
  | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic'
  | 'pulse' | 'pulseSmooth' | 'skeletonWave' | 'blink'

이징 함수 목록

기본 이징

이름	설명
`linear`	등속 (t)
`easeIn`	처음 느리고 끝 빠름 (t²)
`easeOut`	처음 빠르고 끝 느림 (1-(1-t)²)
`easeInOut`	시작/끝 느리고 중간 빠름

Quad / Cubic / Quart / Quint

각 계수(2, 3, 4, 5제곱)에 맞는 In, Out, InOut 변형을 제공한다.

easeInQuad     // t²
easeOutQuad    // 1-(1-t)²
easeInOutQuad  // quadratic InOut

easeInCubic    // t³
easeOutCubic   // 1-(1-t)³
// ...

Sine / Expo / Circ

삼각함수, 지수, 원호 기반 이징.

Bounce / Back / Elastic

이름	설명
`easeOutBounce`	공이 튀기는 효과
`easeInBack`	시작 전 약간 뒤로
`easeOutBack`	끝에서 오버슈트 후 안정화
`easeOutElastic`	탄성 오버슈트

특수 효과 이징

이름	설명
`pulse`	0.5 중심 사인파 (0~1)
`pulseSmooth`	부드러운 펄스
`skeletonWave`	스켈레톤 로딩 웨이브
`blink`	깜빡임 (t < 0.5 → 1, 나머지 → 0)

이징 프리셋

자주 쓰는 조합을 이름으로 제공한다.

const easingPresets = {
  default:  'easeOut',
  smooth:   'easeInOutCubic',
  fast:     'easeOutQuad',
  slow:     'easeInOutSine',
  bouncy:   'easeOutBounce',
  elastic:  'easeOutElastic',
  fade:     'easeInOut',
  scale:    'easeOutBack',
} as const

getEasing()

이름 또는 함수로부터 EasingFunction을 반환한다.

Signature

function getEasing(easingName: unknown): EasingFunction

Parameters

파라미터	타입	설명
`easingName`	`string \	EasingFunction \	unknown`	이징 이름 또는 함수

문자열이고 easing 객체에 없으면 개발 환경에서 경고를 출력하고 easeOut을 반환한다. 'bounce'는 easeOutBounce로 매핑된다.

Usage

import { getEasing } from '@hua-labs/motion-core'

const fn = getEasing('easeOutCubic')
const value = fn(0.5) // 0.875

applyEasing()

진행률 t에 이징 함수를 적용하여 결과를 반환한다.

Signature

function applyEasing(
  t: number,
  easingName: string | EasingFunction
): number

Usage

import { applyEasing } from '@hua-labs/motion-core'

const result = applyEasing(0.5, 'easeOutQuad') // 0.75
const result2 = applyEasing(0.5, (t) => t * t)  // 0.25

safeApplyEasing()

applyEasing의 에러 안전 버전. 예외 발생 시 easeOut 결과를 반환하고 개발 환경에서 경고를 출력한다.

Signature

function safeApplyEasing(t: number, easingName: unknown): number

isValidEasing()

주어진 문자열이 easing 객체의 유효한 키인지 확인한다.

Signature

function isValidEasing(easingName: string): boolean

Usage

import { isValidEasing } from '@hua-labs/motion-core'

isValidEasing('easeOut')    // true
isValidEasing('myCustom')   // false

easing 객체

모든 이징 함수를 하나의 객체로 접근할 수 있다.

Usage

import { easing } from '@hua-labs/motion-core'

const myFn = easing.easeInOutCubic
Object.keys(easing) // 모든 이징 이름 목록

Notes

EasingFunction은 t: 0~1 입력을 받아 0~1 출력을 반환하는 순수 함수다.
MotionEngine의 MotionOptions.easing에는 EasingFunction을 직접 전달해야 한다.
모션 훅의 easing 옵션은 CSS 이징 문자열('ease-out', 'cubic-bezier(...)')을 사용한다. EasingFunction과 다른 타입이다.
getPresetEasing(preset) 함수로 프리셋 이름에서 EasingFunction을 직접 얻을 수도 있다.