--- url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/overview.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 소개 `@react-native-motion-kit/text-motion`은 React Native에서 재사용할 수 있는 텍스트 애니메이션 컴포넌트를 만듭니다. 텍스트 분할, 렌더링, 타이밍, 효과, 접근성을 레시피로 조합한 뒤 컴포넌트로 렌더링합니다. ```txt split → layout(renderer) → timeline → effect → motion/accessibility → component ``` 이 문서는 현재 `0.1.0`의 공개 API를 설명합니다. ## 시작 방법 선택하기 일반적인 제목, 라벨, 제품 설명 애니메이션은 [프리셋](https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md)으로 시작하세요. 애니메이션 단위, 타이밍, 효과를 직접 선택하려면 [커스텀 레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md)를 만드세요. ```tsx import { editorialRise } from '@react-native-motion-kit/text-motion/presets'; const HeroTitle = editorialRise().component(); export function Hero() { return 자연스럽게 움직이는 텍스트; } ``` 컴포넌트의 자식에는 일반 문자열을 전달합니다. 부모가 다시 렌더링되어도 같은 컴포넌트 타입을 사용하도록 React 렌더 함수 밖에서 정의하세요. ## 만들 수 있는 기능 | 목적 | 공개 API | | ------------------------------ | ------------------------------------------------ | | 단어나 사용자가 인식하는 글자 단위로 움직이기 | `words()` 또는 `graphemes()`와 `nativeText()` | | React Native가 실제로 줄바꿈한 줄을 드러내기 | `.split(...)` 없이 `overlayText()`와 `lineReveal()` | | 완성된 문장의 공간을 유지하며 한 글자씩 드러내기 | `graphemes()`, `nativeText()`, `typewriter()` | | 버튼이나 앱 이벤트에 맞춰 다시 재생하기 | `useTextMotionControls()`와 `controls` prop | | 스크롤, 제스처, 앱이 관리하는 애니메이션 따라가기 | Reanimated shared value를 `progress`로 전달 | | 스크린 리더가 문장을 읽을 수 있게 유지하기 | 부모 레이블을 사용하고 장식용 토큰 노드는 접근성 트리에서 숨기기 | `controls`는 재생 명령을 보내고, `progress`는 현재 시각적 상태를 전달합니다. 한 인스턴스에서는 둘 중 하나만 사용할 수 있습니다. ## 범위와 제약 짧은 제목, 헤딩, 라벨, 온보딩 문구, 제품 설명을 대상으로 합니다. 긴 문단, 많은 행, 글자 수가 많은 grapheme 애니메이션은 도입 전에 대상 기기에서 성능을 측정하세요. `nativeText()`는 움직이는 토큰을 컨테이너로 감싸므로 하나의 네이티브 `Text`가 제공하는 모든 동작을 재현하지 않습니다. 중첩된 리치 텍스트, 인라인 링크, 텍스트 선택, 텍스트 `onPress`는 컴포넌트 계약에 포함되지 않습니다. `lines()`는 명시적인 `\n`만 분할합니다. 자동 줄바꿈에는 `overlayText()`를 사용하세요. 현재 공개 API에는 커스텀 효과 팩토리, 렌더러 확장 SDK, Skia 효과, `pause`/`seek`/`reverse`, 스크롤·제스처·화면 포커스·in-view 전용 드라이버가 없습니다. 앱 이벤트는 `controls`로 연결하고 연속적인 shared value는 `progress`로 연결할 수 있습니다. 텍스트 변경은 새 텍스트의 등장만 처리합니다. 퇴장 애니메이션을 위해 이전 텍스트를 유지하거나 스트리밍 텍스트 API를 제공하지 않습니다. [설치](https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md)를 마친 뒤 [빠른 시작](https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md)에서 첫 컴포넌트를 만들어 보세요. 라이브러리의 개발 우선순위와 설계 범위는 [로드맵](https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md)에서 확인할 수 있습니다. --- url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 설치 Text Motion은 React Native Reanimated와 React Native Worklets를 사용합니다. 텍스트 애니메이션을 렌더링하기 전에 앱에서 서로 호환되는 버전으로 설정하세요. ## 요구 사항 패키지가 선언한 peer dependency 최소 버전은 다음과 같습니다. | 의존성 | 선언된 범위 | | ------------------------- | ---------- | | `react` | `>=18.0.0` | | `react-native` | `>=0.76.0` | | `react-native-reanimated` | `>=4.0.0` | | `react-native-worklets` | `>=0.5.0` | 이 범위가 모든 버전 조합의 호환성을 보장하지는 않습니다. [Reanimated 호환성 표](https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/)에서 지원하는 React Native, Reanimated, Worklets 조합을 선택하세요. Reanimated 4는 React Native New Architecture를 요구합니다. ## 패키지 설치 기존 React Native 앱에서는 다음과 같이 설치합니다. ```sh pnpm add @react-native-motion-kit/text-motion react-native-reanimated react-native-worklets ``` npm이나 Yarn을 사용한다면 같은 패키지를 `npm install` 또는 `yarn add`로 설치하세요. Expo 앱에서는 SDK에 맞는 Reanimated와 Worklets 버전을 Expo가 선택하도록 설치합니다. ```sh npx expo install react-native-reanimated react-native-worklets pnpm add @react-native-motion-kit/text-motion ``` SDK가 선택한 버전이 위의 peer dependency 범위를 만족하는지 확인하세요. SDK와 빌드 방식에 필요한 설정은 [Expo Reanimated 가이드](https://docs.expo.dev/versions/latest/sdk/reanimated/)를 따르세요. ## Worklets 설정 사용하는 환경에 맞춰 공식 [Reanimated 시작 가이드](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)와 [Worklets 시작 가이드](https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started/)를 따르세요. Babel을 사용하는 bare React Native 앱에서는 기존 설정의 **마지막** 플러그인으로 Worklets 플러그인을 추가합니다. ```js module.exports = { presets: ['module:@react-native/babel-preset'], plugins: ['react-native-worklets/plugin'], }; ``` 앱에 필요한 다른 preset과 plugin은 유지하세요. Expo의 Babel preset이 해당 SDK에서 플러그인을 설정할 수 있으므로, 중복으로 추가하지 말고 SDK별 설정을 확인하세요. 네이티브 의존성을 추가한 뒤에는 앱에서 사용하는 CocoaPods 절차로 iOS pod를 설치하고 네이티브 앱을 다시 빌드하세요. Babel 설정을 바꿨다면 Metro 캐시를 초기화하고 다시 실행하세요. Text Motion 자체에는 별도 Babel 플러그인, provider, 네이티브 설정이 필요하지 않습니다. ## 공개 진입점에서 가져오기 ```tsx import { defineTextMotion, fade, nativeText, stagger, words, } from '@react-native-motion-kit/text-motion'; import { editorialRise } from '@react-native-motion-kit/text-motion/presets'; ``` 기본 구성 요소는 패키지 루트에서 가져옵니다. 세 가지 프리셋은 `/presets`에서 가져옵니다. 내부 렌더러나 descriptor 파일을 직접 가져오지 마세요. [빠른 시작](https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md)으로 이어서 진행하세요. --- url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 빠른 시작 라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다. [설치](https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md)를 마친 뒤 프리셋을 선택하거나 레시피를 만드세요. 두 방식 모두 재사용할 수 있는 React 컴포넌트를 반환합니다. ## 프리셋으로 시작하기 `editorialRise()`React Native Web 예제 실행 코드 보기 ```tsx import { editorialRise } from '@react-native-motion-kit/text-motion/presets'; const HeroReveal = editorialRise().component(); export function HeroTitle() { return ( 자연스럽게 움직이는 텍스트 ); } ``` `editorialRise()`는 단어 토큰, 중앙에서 시작하는 stagger, rise·fade·scale 조합을 사용합니다. 컴포넌트가 마운트되면 자동으로 재생합니다. ## 단어 등장 효과 만들기 `words()`React Native Web 예제 실행 코드 보기 ```tsx import { defineTextMotion, fade, nativeText, parentLabelPolicy, rise, stagger, words, } from '@react-native-motion-kit/text-motion'; const WordReveal = defineTextMotion() .split(words()) .layout(nativeText()) .timeline(stagger(0.04)) .effect(fade().and(rise({ y: 12 }))) .motion({ kind: 'timing', options: { duration: 420 } }) .accessibility(parentLabelPolicy({ reducedMotion: 'final-state' })) .component(); export function Headline() { return 단어마다 움직임을 더하세요; } ``` 타임라인의 단위는 **초**입니다. `stagger(0.04)`는 보이는 단어를 40ms 간격으로 시작합니다. motion의 `duration` 단위는 **밀리초**입니다. 각 토큰은 자신의 지연 시간이 지난 뒤 420ms 동안 움직입니다. 공백은 레이아웃 공간을 유지하지만 지연 순번을 차지하지 않습니다. 위 접근성 정책은 전체 문장을 한 번 읽도록 제공하고, 동작 줄이기가 활성화되면 최종 상태를 보여 줍니다. ## 실제 렌더링된 줄 드러내기 `overlayText() + lineReveal()`iOS 녹화 코드 보기 폭과 글꼴 설정에 따라 애니메이션할 줄을 결정하려면 `overlayText()`를 사용하세요. 이 렌더러가 줄 측정을 담당하므로 `.split(...)`은 생략합니다. ```tsx import { defineTextMotion, lineReveal, overlayText, stagger, } from '@react-native-motion-kit/text-motion'; const LineTitle = defineTextMotion() .layout(overlayText()) .timeline(stagger(0.08)) .effect(lineReveal({ y: 18 })) .motion({ kind: 'timing', options: { duration: 420 } }) .component(); export function ResponsiveTitle() { return ( 레이아웃이 만든 줄을 따라 움직여요 ); } ``` `lines()`는 다른 용도입니다. 명시적인 줄바꿈 문자만 분할하며 자동 줄바꿈을 측정하지 않습니다. ## 다음 단계 - [레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md) 조합 방식과 [프리셋](https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md) 수정 방법을 알아보세요. - [재생 제어 또는 외부 progress](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 연결하세요. - [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md), [효과](https://react-native-text-motion.pages.dev/ko/api/effects.md), [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)를 비교하세요. --- url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/ai.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # AI 레시피, 프리셋, 재생 제어, 문제 해결을 AI에게 물어볼 때 Text Motion 문서를 함께 제공하세요. ## llms.txt 이 사이트는 AI 도구를 위한 두 가지 파일을 제공합니다. - [llms.txt](https://react-native-text-motion.pages.dev/ko/llms.txt): 개별 문서 링크를 모은 구조화된 인덱스입니다. AI가 필요한 페이지를 직접 가져올 수 있을 때 사용하면 컨텍스트를 줄일 수 있습니다. - [llms-full.txt](https://react-native-text-motion.pages.dev/ko/llms-full.txt): 한국어 문서 전체를 하나로 합친 파일입니다. 여러 기능에 걸친 질문이나 큰 리팩터링에 적합하지만 컨텍스트를 더 많이 사용합니다. 작업에 맞는 URL을 복사하세요. ```txt https://react-native-text-motion.pages.dev/ko/llms.txt https://react-native-text-motion.pages.dev/ko/llms-full.txt ``` ## Markdown 문서 모든 문서 페이지는 Markdown 버전도 제공합니다. 특정 기능 하나만 질문할 때는 관련 페이지만 전달하세요. ```txt https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md ``` AI가 URL을 직접 읽을 수 없다면 파일을 열어 내용을 붙여 넣거나 컨텍스트로 첨부하세요. ## 프롬프트 예시 ```txt https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md를 읽어 주세요. defineTextMotion(), words(), nativeText(), stagger(), fade().and(rise())를 사용해 React Native 단어 리빌을 만들어 주세요. import와 접근성을 고려한 사용 예시를 포함하고, 문서에 있는 API를 사용해 시간 단위를 설명해 주세요. ``` ## 라이브러리 개발 맥락 Text Motion 자체를 수정할 때는 [로드맵 안내](https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md)에서 저장소의 프로젝트 맥락과 상세 계획으로 이동할 수 있습니다. 현재 우선순위, 설계 범위와 보류 후보를 기록한 문서이며, 보류 항목은 출시 약속이 아닙니다. 진행 중인 제안과 우선순위를 정한 이유는 [로드맵 Discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10)에서도 확인할 수 있습니다. --- url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 로드맵 기능 제안, 우선순위와 설계 결정은 [프로젝트 방향·로드맵 Discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10)에서 함께 논의합니다. 라이브러리의 우선순위, 범위와 설계 결정은 저장소의 [프로젝트 맥락과 로드맵](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md)에 기록합니다. 현재 우선순위는 iOS와 Android에서 렌더러 성능과 플랫폼 동작을 검증한 뒤, 그 근거로 추가 API를 라이브러리에 포함할지 판단하는 것입니다. ## 개발 맥락 찾아보기 | 확인할 내용 | 원문 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 다음에 진행할 작업 | [현재 우선순위](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#현재-우선순위) | | 성능 측정과 검증 근거 분류 | [렌더러 성능 체크포인트](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#renderer-performance-checkpoint) | | 구현된 공개 API 범위 | [Stable MVP](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#stable-mvp) | | 보류 후보와 의도적으로 제외한 API | [Deferred](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#deferred) | | Text Motion과 별도 패키지의 경계 | [범위와 로드맵](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#scope--roadmap) | 보류 후보는 출시 약속이 아닙니다. 구현된 동작과 지원 API는 이 사이트의 [API 레퍼런스](https://react-native-text-motion.pages.dev/ko/api/recipe.md)를 참고하세요. 저장소의 로드맵은 원래 README의 맥락과 원본 커밋 링크를 보존합니다. 상세 계획은 그 문서를 기준으로 관리해 여러 곳의 내용이 어긋나지 않게 유지합니다. --- url: https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 레시피 라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다. `defineTextMotion()`은 불변 빌더를 만듭니다. 각 체인 메서드는 새로운 빌더를 반환하므로 기본 레시피를 공유하면서 원본을 바꾸지 않고 여러 변형을 만들 수 있습니다. ## 컴포넌트 만들기 ```tsx import { defineTextMotion, fade, nativeText, rise, stagger, words, } from '@react-native-motion-kit/text-motion'; const base = defineTextMotion() .split(words()) .layout(nativeText()) .timeline(stagger(0.04)) .effect(fade()); const SoftTitle = base .motion({ kind: 'timing', options: { duration: 360 } }) .component(); const RisingTitle = base .effect(rise({ y: 12 })) .motion({ kind: 'spring', options: { damping: 16, stiffness: 140 } }) .component(); export function Titles() { return ( <> 부드럽게 등장해요 움직임을 조금 더해요 ); } ``` 생성한 컴포넌트는 모듈 최상위에서 정의하세요. 렌더 중 `.component()`를 호출하면 매번 새로운 컴포넌트 타입이 생겨 재마운트와 의도하지 않은 자동 재생이 발생할 수 있습니다. ## 각 단계가 결정하는 것 | 단계 | 역할 | | --------------------- | ------------------------------------------- | | `.split(...)` | `nativeText()`가 사용할 원문 토큰 경계 | | `.layout(...)` | 렌더러와 지원하는 애니메이션 단위·효과 | | `.timeline(...)` | 초 단위의 토큰별 시작 지연 | | `.effect(...)` | 효과 추가. 여러 번 호출하면 누적됨 | | `.motion(...)` | 내부 자동 재생과 controls 명령에 사용할 timing 또는 spring | | `.accessibility(...)` | 부모 레이블, 장식용 토큰, 동작 줄이기 정책 | | `.component()` | 문자열 자식을 받는 React 컴포넌트 생성 | | `.recipe()` | 컴포넌트를 만들지 않고 레시피 설정 스냅샷 확인 | `.split()`, `.layout()`, `.timeline()`, `.motion()`, `.accessibility()`를 다시 호출하면 새 빌더에서 해당 설정을 교체합니다. `.effect()`는 기존 효과에 추가합니다. `.recipe()`는 layout을 선택하기 전에도 사용할 수 있습니다. 반환값은 설정 스냅샷으로 취급하고, 컴포넌트를 갱신하려고 직접 수정하지 마세요. ## 렌더러 먼저 선택하기 TypeScript에서는 `.layout(...)`으로 렌더러를 선택한 뒤에만 `.component()`를 사용할 수 있습니다. `.effect(...)`보다 먼저 렌더러를 선택하면 타입이 지원 가능한 효과를 안내합니다. `nativeText()`에서는 splitter를 명시해 단어, grapheme, 커스텀 토큰, 직접 작성한 줄바꿈 단위를 선택합니다. splitter를 생략하면 전체 입력이 하나의 원문 토큰이 됩니다. 기본 동작은 단어 분할이 아닙니다. `overlayText()`는 측정한 네이티브 줄을 애니메이션 단위로 사용합니다. 줄을 움직이려는 경우에도 `.split(...)`을 추가하지 마세요. 타입 시스템이 호환되지 않는 체인을 막고, 런타임 검사도 같은 조합을 거부합니다. ## 호환되는 효과 조합하기 `fade().and(rise()).and(scale())`React Native Web 예제 실행 코드 보기 `.effect(fade().and(rise()))`와 `.effect(fade()).effect(rise())` 모두 fade와 rise를 추가합니다. 기본 효과인 `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`는 두 렌더러에서 사용할 수 있습니다. `typewriter()`는 `nativeText()`를, `lineReveal()`은 `overlayText()`를 요구합니다. splitter, timeline, effect, renderer는 내부 구조를 숨긴 공개 핸들입니다. 내부 descriptor에 접근하는 대신 빌더에 전달하세요. 패키지 루트 API는 커스텀 효과 팩토리나 렌더러 확장 SDK를 내보내지 않습니다. ## 재생 방식 설정하기 `.motion({ kind: 'spring' })`React Native Web 예제 실행 코드 보기 ```tsx import { defineTextMotion, fade, nativeText } from '@react-native-motion-kit/text-motion'; const TimedText = defineTextMotion() .layout(nativeText()) .effect(fade()) .motion({ kind: 'timing', options: { duration: 400 } }) .component(); const SpringText = defineTextMotion() .layout(nativeText()) .effect(fade()) .motion({ kind: 'spring', options: { damping: 16, stiffness: 140 } }) .component(); export function Message() { return ( <> 문장 전체가 함께 나타나요 같은 단위를 스프링으로 움직여요 ); } ``` motion 옵션은 Reanimated의 해당 timing 또는 spring 설정을 따릅니다. 단, `reduceMotion`은 접근성 정책에서 설정합니다. 타임라인 지연의 단위는 초이고 timing의 `duration`은 밀리초입니다. easing처럼 함수인 옵션은 참조로 비교합니다. 다시 렌더링할 때 재생을 유지하려면 같은 함수 참조를 재사용하세요. 인스턴스에 `progress`를 전달하면 앱이 재생을 담당하고 해당 인스턴스의 `.motion()`은 적용되지 않습니다. 레시피가 재생을 담당하면서 개별 명령을 받게 하려면 `controls`를 사용하세요. [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)와 [레시피 API](https://react-native-text-motion.pages.dev/ko/api/recipe.md)를 참고하세요. --- url: https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 프리셋 라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다. 프리셋은 `@react-native-motion-kit/text-motion/presets`에서 가져오는 레시피 팩토리입니다. 각 팩토리는 단어 분할, `nativeText()`, 타임라인, 효과를 미리 선택한 빌더를 반환합니다. `.component()`로 컴포넌트를 만들거나 빌더를 먼저 수정할 수 있습니다. ```tsx import { editorialRise, gentleEmphasis, softWave, } from '@react-native-motion-kit/text-motion/presets'; const HeroTitle = editorialRise().component(); const ProductCopy = softWave().component(); const Label = gentleEmphasis().component(); export function ProductHeader() { return ( <> 단어에 움직임을 더하세요 짧은 제품 설명을 위한 재사용 가능한 애니메이션 ); } ``` ## 기본 레시피 | 팩토리 | 타임라인 | 효과 | | ------------------ | ------------------------------------------ | ---------------------------------------------------- | | `editorialRise()` | `stagger(0.032, { from: 'center' })` | `rise({ y: 14 })`, `fade()`, `scale({ from: 0.98 })` | | `softWave()` | `wave({ amplitude: 0.06, wavelength: 5 })` | `fade()`, `rise({ y: 8 })` | | `gentleEmphasis()` | `stagger(0.024)` | `pulse({ scale: 1.06 })`, `fade()` | 세 팩토리는 모두 인수를 받지 않습니다. 지연 값의 단위는 초입니다. 별도의 `.motion()`이나 접근성 정책을 지정하지 않으므로 직접 설정하지 않으면 렌더러 기본값을 사용합니다. `editorialRise()`는 중앙에서 펼쳐지는 제목에 어울립니다. `softWave()`는 단어의 시작 시간을 달리해 부드러운 리듬을 만듭니다. `gentleEmphasis()`는 애니메이션 중간 부근에서 토큰을 잠시 확대했다가 최종 크기로 돌아오며, 반복 재생하지 않습니다. ## 프리셋 미리보기 ### `editorialRise()` `editorialRise()`React Native Web 예제 실행 코드 보기 ### `softWave()` `softWave()`React Native Web 예제 실행 코드 보기 ### `gentleEmphasis()` `gentleEmphasis()`React Native Web 예제 실행 코드 보기 ## 프리셋 수정하기 ```tsx import { parentLabelPolicy, stagger, } from '@react-native-motion-kit/text-motion'; import { editorialRise } from '@react-native-motion-kit/text-motion/presets'; const base = editorialRise(); const StandardTitle = base.component(); const SlowerTitle = base .timeline(stagger(0.06, { from: 'start' })) .motion({ kind: 'timing', options: { duration: 500 } }) .accessibility(parentLabelPolicy({ reducedMotion: 'final-state' })) .component(); export function Titles() { return ( <> 기본은 중앙에서 시작해요 처음부터 천천히 나타나요 ); } ``` 빌더는 불변이므로 수정한 변형이 `StandardTitle`을 바꾸지 않습니다. 뒤에서 호출한 `.timeline(...)`은 프리셋 타임라인을 교체합니다. `.effect(...)`는 기존 효과를 교체하지 않고 추가합니다. 효과 구성을 바꾸거나 `overlayText()`로 실제 줄 단위 레시피를 만들려면 `defineTextMotion()`에서 시작하세요. 프리셋도 커스텀 레시피와 같은 [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)와 [재생 입력](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)을 사용합니다. 생성한 컴포넌트는 렌더 함수 밖에 정의하고 자식으로 일반 문자열을 전달하세요. --- url: https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md --- > For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt. # 재생 제어 라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다. 컴포넌트의 자동 재생, 이벤트 기반 명령, 앱이 소유한 Reanimated 공유값 중 재생을 제어할 방식을 선택합니다. | 방식 | 입력 | 재생 담당 | | ------ | --------------------- | ----------------------------------- | | 자동 재생 | 재생 관련 prop 없음 | Text Motion이 입력 변화에 따라 재생합니다. | | 명령 | `controls={controls}` | 앱이 명령을 보내고 Text Motion이 레시피를 실행합니다. | | 외부 진행률 | `progress={progress}` | 앱이 값과 애니메이션 곡선을 직접 제어합니다. | ## 자동 재생과 텍스트 변경 `Autoplay`React Native Web 예제 실행 코드 보기 마운트하면 화면에 보이는 애니메이션 토큰이 초기 스타일에서 최종 스타일로 재생됩니다. `controls`를 전달해도 마운트 시 자동 재생은 유지됩니다. 첫 명령을 기다리는 방식으로 바뀌지는 않습니다. - 같은 텍스트와 레시피로 다시 렌더링하면 진행 중인 재생을 유지합니다. - 텍스트가 바뀌면 토큰 형태가 같아도 변경된 토큰의 애니메이션을 다시 재생합니다. - 실제 효과, 타이밍, 모션 설정이 바뀌면 관련 토큰을 초기화하고 새 설정을 적용합니다. easing 같은 함수 옵션은 참조로 비교하므로 재생을 유지하려면 같은 함수 참조를 사용하세요. - 공백과 정적 토큰은 레이아웃을 유지하지만 애니메이션이나 모션 인덱스를 소비하지 않습니다. 텍스트 변경은 새 텍스트의 진입만 처리합니다. 이전 텍스트의 퇴장, 크로스페이드, 이전·새 토큰 간 전환은 제공하지 않습니다. 외부 진행률을 전달한 경우 새 텍스트도 현재 공유값을 사용하며 자동으로 처음부터 재생하지 않습니다. 명령은 현재 렌더링된 텍스트에 적용됩니다. React가 컴포넌트 정체성을 유지할 수 있도록 레시피 컴포넌트는 렌더 함수 밖에서 만드세요. [레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md)를 참고하세요. ## 이벤트 기반 controls `play() / replay() / reset() / stop()`React Native Web 예제 실행 코드 보기 `useTextMotionControls()`는 참조가 유지되는 명령 채널을 반환합니다. 명령을 받을 컴포넌트에 명시적으로 전달합니다. ```tsx 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 ( 함께 재생하는 제목 같은 명령 채널을 사용하는 부제목