#재생 제어

라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.

컴포넌트의 자동 재생, 이벤트 기반 명령, 앱이 소유한 Reanimated 공유값 중 재생을 제어할 방식을 선택합니다.

#자동 재생과 텍스트 변경

마운트하면 화면에 보이는 애니메이션 토큰이 초기 스타일에서 최종 스타일로 재생됩니다. controls를 전달해도 마운트 시 자동 재생은 유지됩니다. 첫 명령을 기다리는 방식으로 바뀌지는 않습니다.

• 같은 텍스트와 레시피로 다시 렌더링하면 진행 중인 재생을 유지합니다.
• 텍스트가 바뀌면 토큰 형태가 같아도 변경된 토큰의 애니메이션을 다시 재생합니다.
• 실제 효과, 타이밍, 모션 설정이 바뀌면 관련 토큰을 초기화하고 새 설정을 적용합니다. easing 같은 함수 옵션은 참조로 비교하므로 재생을 유지하려면 같은 함수 참조를 사용하세요.
• 공백과 정적 토큰은 레이아웃을 유지하지만 애니메이션이나 모션 인덱스를 소비하지 않습니다.

텍스트 변경은 새 텍스트의 진입만 처리합니다. 이전 텍스트의 퇴장, 크로스페이드, 이전·새 토큰 간 전환은 제공하지 않습니다. 외부 진행률을 전달한 경우 새 텍스트도 현재 공유값을 사용하며 자동으로 처음부터 재생하지 않습니다. 명령은 현재 렌더링된 텍스트에 적용됩니다.

React가 컴포넌트 정체성을 유지할 수 있도록 레시피 컴포넌트는 렌더 함수 밖에서 만드세요. 레시피를 참고하세요.

#이벤트 기반 controls

useTextMotionControls()는 참조가 유지되는 명령 채널을 반환합니다. 명령을 받을 컴포넌트에 명시적으로 전달합니다.

import { Button, View } from 'react-native';
import {
  defineTextMotion,
  fade,
  nativeText,
  rise,
  stagger,
  useTextMotionControls,
  words,
} from '@react-native-motion-kit/text-motion';

const Reveal = defineTextMotion()
  .split(words())
  .layout(nativeText())
  .timeline(stagger(0.04))
  .effect(fade().and(rise({ y: 12 })))
  .motion({ kind: 'timing', options: { duration: 420 } })
  .component();

export function Headlines() {
  const controls = useTextMotionControls();

  return (
    <View>
      <Reveal controls={controls}>함께 재생하는 제목</Reveal>
      <Reveal controls={controls}>같은 명령 채널을 사용하는 부제목</Reveal>
      <Button title="재생" onPress={controls.play} />
      <Button title="다시 재생" onPress={controls.replay} />
      <Button title="초기화" onPress={controls.reset} />
      <Button title="정지" onPress={controls.stop} />
    </View>
  );
}

명령은 같은 controls 객체에 연결된 모든 마운트된 컴포넌트에 전달되며, 각 컴포넌트는 자신의 레시피로 실행합니다. 명령은 저장된 재생 상태나 이후 마운트할 컴포넌트를 위한 대기열이 아닙니다. 연결이 해제되거나 언마운트되면 구독도 해제됩니다.

stop() 후 play()는 정확한 일시 정지·재개 API가 아니며 원래 일정의 남은 시간을 그대로 이어갈 것을 보장하지 않습니다. 처음부터 다시 시작하려면 replay()를 사용하세요. 명시적인 모션 감소 최종 상태 정책이 활성화돼 있으면 초기화나 다시 재생보다 최종 표시 상태가 우선합니다.

버튼, 앱에서 연결한 화면 포커스 이벤트, 온보딩 단계에는 controls를 사용하세요. 재생용 provider/context API나 공개 컴포넌트 ref API는 제공하지 않습니다.

#앱이 소유한 progress

앱이 이미 소유한 다른 애니메이션, 스크롤 값, 제스처 값을 따라야 한다면 Reanimated의 SharedValue<number>를 사용합니다.

import { Button, View } from 'react-native';
import { useSharedValue, withTiming } from 'react-native-reanimated';
import {
  defineTextMotion,
  fade,
  nativeText,
  rise,
  stagger,
  words,
} from '@react-native-motion-kit/text-motion';

const ProgressReveal = defineTextMotion()
  .split(words())
  .layout(nativeText())
  .timeline(stagger(0.08))
  .effect(fade().and(rise({ y: 12 })))
  .component();

export function ProgressExample() {
  const progress = useSharedValue(0);

  return (
    <View>
      <ProgressReveal progress={progress}>
        문장 전체를 하나의 진행률로 제어합니다
      </ProgressReveal>
      <Button
        title="재생"
        onPress={() => {
          progress.value = withTiming(1, { duration: 720 });
        }}
      />
      <Button title="초기화" onPress={() => { progress.value = 0; }} />
    </View>
  );
}

0은 초기 스타일, 1은 최종 스타일입니다. 이 범위를 벗어난 유한한 값은 보정하고, 유한하지 않은 값은 0으로 처리합니다. progress를 전달하면 내부 자동 재생이 비활성화되고 해당 인스턴스에서는 레시피의 .motion() 설정을 사용하지 않습니다. 시간과 easing은 공유값을 갱신하는 곳에서 설정하세요.

이 값은 효과 타임라인 전체의 진행률입니다. 토큰 지연 d와 가장 큰 토큰 지연 D를 초 단위로 나타내면 현재 매핑은 토큰별 구간을 1.0으로 고정해 계산합니다.

localProgress = clamp(progress * (D + 1) - d, 0, 1)

타임라인은 각 토큰이 시작하는 시점을 계속 결정합니다. 공백은 지연 슬롯을 사용하지 않습니다. 이 매핑은 토큰별 재생 시간 API가 아닙니다.

#Typewriter의 진행률

미리보기는 타임라인 진행률과 현재 표시된 글자 수를 따로 보여줍니다. 글자 수는 공백을 제외하고 문장부호와 이모지를 포함하며, 재생 중이나 진행률을 되돌릴 때도 갱신됩니다.

typewriter()는 토큰의 로컬 진행률이 0보다 커지면 해당 토큰을 표시합니다. 진행률은 표시된 문자 수의 비율이 아닙니다. 보이는 문자 10개에 stagger(0.05)를 사용하면 약 0.310345를 넘는 시점에 모든 문자가 보입니다. 진행률을 줄여 시작 임계점을 다시 지나면 문자가 숨겨질 수 있습니다. 시간상 일정한 간격으로 임계점을 통과하려면 외부 타이밍 곡선을 선형으로 설정하세요.

이 효과는 완성된 문장의 레이아웃을 유지합니다. 커서나 스트리밍 텍스트 API는 제공하지 않습니다. 효과와 예제를 참고하세요.

#지원 범위

controls와 progress는 TypeScript와 런타임 모두에서 함께 사용할 수 없습니다. 전용 pause, seek, reverse, 스크롤, 제스처, in-view, 화면 포커스 드라이버는 제공하지 않습니다. 앱의 이벤트는 controls에, 연속적인 값은 progress에 연결하세요.

모션 감소 동작은 접근성, 지원하는 텍스트·접근성 prop은 컴포넌트 props를 참고하세요.