콘텐츠로 이동

뷰 전환 라우터 API 참조

추가된 버전: astro@3.0.0

이 모듈은 뷰 전환 API 및 클라이언트 측 라우터를 제어하고 상호 작용하는 함수를 제공합니다.

기능 및 사용 예시는 뷰 전환 가이드를 참조하세요.

astro:transitions에서 가져오기

섹션 제목: “astro:transitions에서 가져오기”
import {
  ClientRouter,
  fade,
  slide,
} from 'astro:transitions';

<ClientRouter />

섹션 제목: “<ClientRouter />”

추가된 버전: astro@5.0.0

원하는 모든 페이지의 <head>에 <ClientRouter /> 라우팅 컴포넌트를 가져오고 추가하여 개별 페이지에서 트랜지션을 사용하도록 선택합니다.

src/pages/index.astro
---
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ClientRouter />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

페이지 요소와 컴포넌트에 라우터 제어 및 전환 지시어를 추가하는 방법에 대해 자세히 알아보세요.

<ClientRouter /> 컴포넌트는 다음 props를 허용합니다.

fallback

타입: Fallback
기본값: animate

뷰 전환 API를 지원하지 않는 브라우저에서 사용할 대체 전략을 정의합니다.

fade

섹션 제목: “fade”

타입: (opts: { duration?: string | number }) => TransitionDirectionalAnimations

추가된 버전: astro@3.0.0

기본적으로 제공되는 fade 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다.

---
import { fade } from 'astro:transitions';
---


<!-- 기본 지속 시간을 사용한 페이드 트랜지션 -->
<div transition:animate="fade" />


<!-- 400 밀리초 동안 지속되는 페이드 트랜지션 -->
<div transition:animate={fade({ duration: '0.4s' })} />

slide

섹션 제목: “slide”

타입: (opts: { duration?: string | number }) => TransitionDirectionalAnimations

추가된 버전: astro@3.0.0

기본적으로 제공되는 slide 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다.

---
import { slide } from 'astro:transitions';
---


<!-- 기본 지속 시간을 사용한 슬라이드 트랜지션 -->
<div transition:animate="slide" />


<!-- 400 밀리초 동안 지속되는 슬라이드 트랜지션 -->
<div transition:animate={slide({ duration: '0.4s' })} />

astro:transitions/client에서 가져오기

섹션 제목: “astro:transitions/client에서 가져오기”
import {
  getFallback,
  navigate,
  supportsViewTransitions,
  swapFunctions,
  transitionEnabledOnThisPage,
  /* 다음 항목들은 v6에서 사용 중단될 예정입니다. */
  isTransitionBeforePreparationEvent,
  isTransitionBeforeSwapEvent,
  TRANSITION_AFTER_PREPARATION,
  TRANSITION_AFTER_SWAP,
  TRANSITION_BEFORE_PREPARATION,
  TRANSITION_BEFORE_SWAP,
  TRANSITION_PAGE_LOAD,
} from 'astro:transitions/client';
섹션 제목: “navigate()”

타입: (href: string, options?: Options) => void

추가된 버전: astro@3.2.0

뷰 전환 API를 사용하여 지정된 href로 탐색을 실행합니다.

이 함수 시그니처는 브라우저 Navigation API의 navigate 함수를 기반으로 합니다. 이 함수는 Navigation API를 기반으로 하지만, 페이지를 다시 로드하지 않고 탐색할 수 있도록 History API 위에 구현되어 있습니다.

navigate()는 href 매개변수에 대한 검증을 수행하지 않습니다. 이동할 URL을 결정하기 위해 사용자 입력을 사용하는 경우 사용자 입력을 검증하세요.

history 옵션

섹션 제목: “history 옵션”

타입: 'auto' | 'push' | 'replace'
기본값: 'auto'

추가된 버전: astro@3.2.0

이 탐색을 브라우저 기록에 추가하는 방법을 정의합니다.

  • 'push': 라우터는 history.pushState를 사용하여 브라우저 기록에 새 항목을 생성합니다.
  • 'replace': 라우터는 history.replaceState를 사용하여 탐색에 새 항목을 추가하지 않고 URL을 업데이트합니다.
  • 'auto' (기본값): 라우터는 history.pushState를 시도하지만, URL을 전환할 수 없는 경우 현재 URL은 브라우저 기록을 변경하지 않고 그대로 유지됩니다.

이 옵션은 브라우저 Navigation API의 history 옵션을 따르지만, Astro 프로젝트에서 발생할 수 있는 경우를 위해 단순화되었습니다.

formData 옵션

섹션 제목: “formData 옵션”

타입: FormData

추가된 버전: astro@3.5.0

POST 요청을 위한 FormData 객체입니다.

이 옵션을 제공하면 탐색 대상 페이지에 대한 요청이 양식 데이터 객체를 콘텐츠로 하는 POST 요청으로 전송됩니다.

트랜지션이 활성화된 HTML 양식을 제출하면 페이지 새로 고침이 있는 기본 탐색 대신 이 메서드가 사용됩니다. 이 메서드를 호출하면 프로그래밍 방식으로 동일한 동작을 트리거할 수 있습니다.

info 옵션

섹션 제목: “info 옵션”

타입: any

추가된 버전: astro@3.6.0

이 탐색으로 인해 발생하는 astro:before-preparation 및 astro:before-swap 이벤트에 포함될 임의의 데이터입니다.

이 옵션은 브라우저 Navigation API의 info 옵션을 모방합니다.

state 옵션

섹션 제목: “state 옵션”

타입: any

추가된 버전: astro@3.6.0

이 탐색에서 생성된 NavitationHistoryEntry 객체에 연결할 임의의 데이터입니다. 이 데이터는 History API의 history.getState 함수를 사용하여 검색할 수 있습니다.

이 옵션은 브라우저 Navigation API의 state 옵션을 모방합니다.

sourceElement 옵션

섹션 제목: “sourceElement 옵션”

타입: Element

추가된 버전: astro@3.6.0

존재하는 경우, 이 탐색을 트리거한 요소입니다. 이 요소는 다음 이벤트에서 사용할 수 있습니다.

supportsViewTransitions

섹션 제목: “supportsViewTransitions”

타입: boolean

추가된 버전: astro@3.2.0

현재 브라우저에서 트랜지션이 지원되고 활성화되어 있는지 여부입니다.

transitionEnabledOnThisPage()

섹션 제목: “transitionEnabledOnThisPage()”

타입: () => boolean

추가된 버전: astro@3.2.0

현재 페이지에 클라이언트 측 탐색을 위한 트랜지션이 활성화되어 있는지 여부입니다. 트랜지션이 있는 페이지에서 다르게 동작하는 컴포넌트를 만드는 데 사용할 수 있습니다.

getFallback()

섹션 제목: “getFallback()”

타입: () => Fallback
기본값: animate

추가된 버전: astro@3.6.0

트랜지션을 지원하지 않는 브라우저에서 사용할 대체 전략을 반환합니다. (기본값은 animate)

대체 동작을 선택하고 구성하는 방법은 대체 제어 가이드를 참조하세요.

swapFunctions

섹션 제목: “swapFunctions”

타입: object

추가된 버전: astro@4.15.0

Astro의 기본 교체 함수를 빌드하는 데 사용되는 유틸리티 함수가 포함된 객체입니다. 사용자 정의 함수를 만들때 유용할 수 있습니다.

swapFunctions는 다음과 같은 메서드를 제공합니다:

deselectScripts()

섹션 제목: “deselectScripts()”

타입: (newDocument: Document) => void

새 문서에서 실행해서는 안 되는 스크립트를 표시합니다. 이러한 스크립트는 이미 현재 문서에 있으며 data-astro-rerun을 사용하여 다시 실행하도록 플래그가 지정되지 않습니다.

swapRootAttributes()

섹션 제목: “swapRootAttributes()”

타입: (newDocument: Document) => void

lang 속성과 같은 문서 루트 간 속성을 교체합니다. 여기에는 data-astro-transition과 같은 Astro에서 삽입한 내부 속성도 포함되어 있어, 트랜지션 방향을 Astro에서 생성된 CSS 규칙에 사용할 수 있습니다.

사용자 정의 교체 함수를 만들 때, 트랜지션의 애니메이션이 깨지지 않도록 이 함수를 호출하는 것이 중요합니다.

swapHeadElements()

섹션 제목: “swapHeadElements()”

타입: (newDocument: Document) => void

현재 문서의 <head>에서 새 문서에 유지되지 않는 모든 요소를 제거합니다. 그런 다음 새 문서의 <head>에 있는 모든 새 요소를 현재 문서의 <head>에 추가합니다.

saveFocus()

섹션 제목: “saveFocus()”

타입: () => () => void

현재 페이지에서 포커스된 요소를 저장하고, 포커스된 요소가 유지되는 경우, 호출 시 해당 요소에 포커스를 제공하는 함수를 반환합니다.

swapBodyElement()

섹션 제목: “swapBodyElement()”

타입: (newBody: Element, oldBody: Element) => void

이전 body를 새 body로 교체합니다. 그런 다음 이전 body에서 유지되어야 하는 모든 요소를 검토하고 새 body에서 일치하는 요소를 찾아 이전 요소를 다시 제자리로 바꿉니다.

더 이상 지원되지 않는 기능

섹션 제목: “더 이상 지원되지 않는 기능”

다음 가져오기 항목들은 v6에서 사용 중단될 예정입니다. 프로젝트에서 계속 사용할 수 있지만, 지금 코드를 업데이트하는 것이 좋습니다.

isTransitionBeforePreparationEvent()

타입: (value: any) => boolean

추가된 버전: astro@3.6.0

지정된 값이 TransitionBeforePreparationEvent와 일치하는지 여부를 결정합니다. 이는 이벤트 리스너에서 이벤트의 타입을 좁혀야 할 때 유용할 수 있습니다.

src/pages/index.astro
---
---


<script>
  import {
    isTransitionBeforePreparationEvent,
    TRANSITION_BEFORE_PREPARATION,
  } from "astro:transitions/client";


  function listener(event: Event) {
    const setting = isTransitionBeforePreparationEvent(event) ? 1 : 2;
    /* 설정을 사용한 작업 */
  }


  document.addEventListener(TRANSITION_BEFORE_PREPARATION, listener);
</script>

isTransitionBeforeSwapEvent()

타입: (value: any) => boolean

추가된 버전: astro@3.6.0

주어진 값이 TransitionBeforeSwapEvent와 일치하는지 여부를 결정합니다. 이는 이벤트 리스너에서 이벤트의 타입을 좁혀야 할 때 유용할 수 있습니다.

src/pages/index.astro
---
---


<script>
  import {
    isTransitionBeforeSwapEvent,
    TRANSITION_BEFORE_SWAP,
  } from "astro:transitions/client";


  function listener(event: Event) {
    const setting = isTransitionBeforeSwapEvent(event) ? 1 : 2;
    /* 설정을 사용한 작업 */
  }


  document.addEventListener(TRANSITION_BEFORE_SWAP, listener);
</script>

TRANSITION_BEFORE_PREPARATION

타입: 'astro:before-preparation'

추가된 버전: astro@3.6.0

이벤트를 정의할 때 astro:before-preparation 이벤트 이름을 일반 텍스트로 작성하는 것을 피하기 위한 상수입니다.

src/pages/index.astro
---
---


<script>
  import { TRANSITION_BEFORE_PREPARATION } from "astro:transitions/client";


  document.addEventListener(TRANSITION_BEFORE_PREPARATION, () => {
    /* 리스너 로직 */
  });
</script>

TRANSITION_AFTER_PREPARATION

타입: 'astro:after-preparation'

추가된 버전: astro@3.6.0

이벤트를 정의할 때 astro:after-preparation 이벤트 이름을 일반 텍스트로 작성하는 것을 피하기 위한 상수입니다.

src/pages/index.astro
---
---


<script>
  import { TRANSITION_AFTER_PREPARATION } from "astro:transitions/client";


  document.addEventListener(TRANSITION_AFTER_PREPARATION, () => {
    /* 리스너 로직 */
  });
</script>

TRANSITION_BEFORE_SWAP

타입: 'astro:before-swap'

추가된 버전: astro@3.6.0

이벤트를 정의할 때 astro:before-swap 이벤트 이름을 일반 텍스트로 작성하는 것을 피하기 위한 상수입니다.

src/pages/index.astro
---
---


<script>
  import { TRANSITION_BEFORE_SWAP } from "astro:transitions/client";


  document.addEventListener(TRANSITION_BEFORE_SWAP, () => {
    /* 리스너 로직 */
  });
</script>

TRANSITION_AFTER_SWAP

타입: 'astro:after-swap'

추가된 버전: astro@3.6.0

이벤트를 정의할 때 astro:after-swap 이벤트 이름을 일반 텍스트로 작성하는 것을 피하기 위한 상수입니다.

src/pages/index.astro
---
---


<script>
  import { TRANSITION_AFTER_SWAP } from "astro:transitions/client";


  document.addEventListener(TRANSITION_AFTER_SWAP, () => {
    /* 리스너 로직 */
  });
</script>

TRANSITION_PAGE_LOAD

타입: 'astro:page-load'

추가된 버전: astro@3.6.0

이벤트를 정의할 때 astro:page-load 이벤트 이름을 일반 텍스트로 작성하는 것을 피하기 위한 상수입니다.

src/pages/index.astro
---
---


<script>
  import { TRANSITION_PAGE_LOAD } from "astro:transitions/client";


  document.addEventListener(TRANSITION_PAGE_LOAD, () => {
    /* 리스너 로직 */
  });
</script>

astro:transitions/client types

섹션 제목: “astro:transitions/client types”
import type {
  Direction,
  Fallback,
  NavigationTypeString,
  Options,
  TransitionBeforePreparationEvent,
  TransitionBeforeSwapEvent,
} from 'astro:transitions/client';

Direction

섹션 제목: “Direction”

타입: 'forward' | 'back'

추가된 버전: astro@3.2.0

애니메이션 방향의 유니온입니다.

  • forward: 기록에서 다음 페이지로 이동하거나 새 페이지로 이동합니다.
  • back: 기록에서 이전 페이지로 이동합니다.

Fallback

섹션 제목: “Fallback”

타입: 'none' | 'animate' | 'swap'

추가된 버전: astro@3.2.0

뷰 전환을 지원하지 않는 브라우저에서 사용할 대체 전략의 유니온입니다.

  • animate: Astro는 페이지 콘텐츠를 업데이트하기 전에 사용자 정의 속성을 사용하여 뷰 전환을 시뮬레이션합니다.
  • swap: Astro는 페이지를 애니메이션하려고 시도하지 않습니다. 대신, 이전 페이지는 새 페이지로 즉시 교체됩니다.
  • none: Astro는 어떠한 애니메이션 페이지 전환도 수행하지 않습니다. 대신, 뷰 전환을 지원하지 않는 브라우저에서는 전체 페이지 탐색이 이루어집니다.
ClientRouter를 사용하여 대체 전략 제어에 대해 자세히 알아보세요.
섹션 제목: “NavigationTypeString”

타입: 'push' | 'replace' | 'traverse'

추가된 버전: astro@3.6.0

지원되는 히스토리 탐색 이벤트의 유니온입니다.

TransitionBeforePreparationEvent

섹션 제목: “TransitionBeforePreparationEvent”

타입: Event

추가된 버전: astro@3.6.0

astro:before-preparation 이벤트를 나타냅니다. 이는 리스너가 받는 이벤트의 타입을 지정하는 데 유용할 수 있습니다.

src/pages/index.astro
---
---


<script>
  import {
    TRANSITION_BEFORE_PREPARATION,
    type TransitionBeforePreparationEvent
  } from "astro:transitions/client";


  function listener(event: TransitionBeforePreparationEvent) {
    /* 추가 작업 */
  }


  document.addEventListener(TRANSITION_BEFORE_PREPARATION, listener);
</script>

TransitionBeforeSwapEvent

섹션 제목: “TransitionBeforeSwapEvent”

타입: Event

추가된 버전: astro@3.6.0

astro:before-swap 이벤트를 나타냅니다. 이는 리스너가 받는 이벤트의 타입을 지정하는 데 유용할 수 있습니다.

src/pages/index.astro
---
---


<script>
  import {
    TRANSITION_BEFORE_SWAP,
    type TransitionBeforeSwapEvent
  } from "astro:transitions/client";


  function listener(event: TransitionBeforeSwapEvent) {
    /* 추가 작업 */
  }


  document.addEventListener(TRANSITION_BEFORE_SWAP, listener);
</script>

라이프사이클 이벤트

섹션 제목: “라이프사이클 이벤트”

astro:before-preparation 이벤트

섹션 제목: “astro:before-preparation 이벤트”

타입: TransitionBeforePreparationEvent

추가된 버전: astro@3.6.0

뷰 전환 라우터를 사용하여 탐색을 시작할 때 전송되는 이벤트입니다. 이 이벤트는 요청이 이루어지고 브라우저 상태가 변경되기 전에 발생합니다.

이 이벤트에는 속성이 있습니다:

이 이벤트의 사용 방법에 대한 자세한 내용은 뷰 전환 가이드에서 확인하세요.

astro:after-preparation 이벤트

섹션 제목: “astro:after-preparation 이벤트”

타입: Event

추가된 버전: astro@3.6.0

뷰 전환 라우터를 사용하는 탐색에서 다음 페이지가 로드된 후 전송되는 이벤트입니다.

이 이벤트에는 속성이 없습니다.

이 이벤트의 사용 방법에 대한 자세한 내용은 뷰 전환 가이드에서 확인하세요.

astro:before-swap 이벤트

섹션 제목: “astro:before-swap 이벤트”

타입: TransitionBeforeSwapEvent

추가된 버전: astro@3.6.0

다음 페이지가 구문 분석되고, 준비되고, 트랜지션을 준비하면서 문서에 링크된 후, 문서 간 콘텐츠가 교환되기 전에 전송되는 이벤트입니다.

이 이벤트는 취소할 수 없습니다. preventDefault()를 호출하는 것은 아무 작업도 하지 않습니다.

이 이벤트에는 속성이 있습니다:

이 이벤트의 사용 방법에 대한 자세한 내용은 뷰 전환 가이드에서 확인하세요.

astro:after-swap 이벤트

섹션 제목: “astro:after-swap 이벤트”

타입: Event

페이지의 콘텐츠가 교체된 후, 트랜지션이 끝나기 전에 전달되는 이벤트입니다.

기록 항목과 스크롤 위치가 업데이트된 후, 이 이벤트가 트리거됩니다.

astro:page-load 이벤트

섹션 제목: “astro:page-load 이벤트”

타입: Event

트랜지션을 사용하는 탐색이나 브라우저의 기본 기능으로 페이지 로드가 완료된 후 전달되는 이벤트입니다.

페이지에서 트랜지션이 활성화되면 일반적으로 DOMContentLoaded에서 실행되는 코드가 이 이벤트에서 실행되도록 변경되어야 합니다.

라이프사이클 이벤트 속성

섹션 제목: “라이프사이클 이벤트 속성”

추가된 버전: astro@3.6.0

다음 속성들은 astro:before-preparation 및 astro:before-swap 이벤트에서 모두 사용할 수 있지만, 일부 속성은 둘 중 하나에서만 사용할 수 있습니다.

info

섹션 제목: “info”

타입: any

탐색 중에 정의된 임의의 데이터입니다.

이는 navigate() 함수의 info 옵션에 전달된 리터럴 값입니다.

sourceElement

섹션 제목: “sourceElement”

타입: Element | undefined

탐색을 트리거한 요소입니다. 예를 들어 클릭된 <a> 요소가 될 수 있습니다.

navigate() 함수를 사용할 때는 호출에서 지정된 요소가 됩니다.

newDocument

섹션 제목: “newDocument”

타입: Document

탐색의 다음 페이지에 대한 문서입니다. 이 문서의 내용은 현재 문서의 내용 대신 교체됩니다.

섹션 제목: “navigationType”

타입: NavigationTypeString

어떤 종류의 기록 탐색이 일어나고 있나요.

  • push: 새 페이지에 대한 새 NavigationHistoryEntry가 만들어지고 있습니다.
  • replace: 현재 NavigationHistoryEntry가 새 페이지의 항목으로 대체되고 있습니다.
  • traverse: NavigationHistoryEntry이 생성되지 않습니다. 히스토리 내 위치가 변경됩니다. 순회 방향은 direction 속성에서 지정됩니다.

direction

섹션 제목: “direction”

타입: string

전환의 방향을 나타냅니다.

  • astro:before-preparation 이벤트에서는 방향을 사용자 정의하는 데 사용할 수 있습니다. 이 속성은 쓰기가 가능하며 모든 문자열을 허용합니다.
  • astro:before-swap 이벤트에서는 전환 방향을 검색하는 데 사용할 수 있습니다. 이 속성은 읽기 전용이며, 그 값은 미리 정의된 Direction이거나 astro:before-preparation 이벤트 리스너가 설정했을 수도 있는 모든 문자열일 수 있습니다.

from

섹션 제목: “from”

타입: URL

The URL of the page initiating the navigation. 탐색을 시작하는 페이지의 URL입니다.

to

섹션 제목: “to”

타입: URL

탐색 중인 페이지의 URL입니다. 이 속성을 수정할 수 있으며, 라이프사이클이 끝날 때의 값이 다음 페이지의 NavigationHistoryEntry에 사용됩니다.

formData

섹션 제목: “formData”

타입: FormData | undefined
사용 가능: astro:before-preparation 이벤트

설정된 경우, 일반적인 GET 요청 대신, 주어진 FormData 객체를 콘텐츠로 하는 POST 요청이 to URL로 전송됩니다.

트랜지션이 활성화된 HTML 양식을 제출할 때 이 필드는 양식의 데이터로 자동 설정됩니다. navigate() 함수를 사용하는 경우 이 값은 옵션에 지정된 것과 동일합니다.

loader()

섹션 제목: “loader()”

타입: () => Promise<void>
사용 가능: astro:before-preparation 이벤트

탐색에서 다음 단계 (다음 페이지 로딩)를 구현합니다. 이 구현을 재정의하여 동작을 추가할 수 있습니다.

viewTransition

섹션 제목: “viewTransition”

타입: ViewTransition
사용 가능: astro:before-swap 이벤트

이 탐색에 사용된 트랜지션 객체입니다. 뷰 전환 API를 지원하지 않는 브라우저에서는 편의를 위해 동일한 API를 구현하지만 DOM 통합이 없는 객체입니다.

swap()

섹션 제목: “swap()”

타입: () => void
사용 가능: astro:before-swap 이벤트

기본 문서 교체 로직을 호출합니다. 기본적으로 이 구현은 다음 함수들을 순서대로 호출합니다.

  1. deselectScripts()
  2. swapRootAttributes()
  3. swapHeadElements()
  4. saveFocus()
  5. swapBodyElement()
뷰 전환 가이드에서 사용자 정의 교체를 함수 구현하는 방법에 대해 자세히 알아보세요.
기여하기 커뮤니티 후원하기