View Transitions API 참조

Added in: astro@3.0.0

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

기능 및 사용 예시는 View Transitions 가이드를 참조하세요.

`astro:transitions`에서 가져오기

import { ViewTransitions, fade, slide } from 'astro:transitions';

`<ViewTransitions />`

Added in: astro@3.0.0

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

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

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

`fade`

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

Added in: astro@3.0.0

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

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

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

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

`slide`

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

Added in: 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`에서 가져오기

<script>
  import {
    navigate,
    supportsViewTransitions,
    transitionEnabledOnThisPage,
    getFallback,
    swapFunctions,
  } from 'astro:transitions/client';
</script>

`navigate()`

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

Added in: astro@3.2.0

View Transitions API를 사용하여 지정된 href로 탐색을 실행하는 함수입니다.

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

`history` 옵션

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

Added in: astro@3.2.0

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

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

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

`formData` 옵션

타입: FormData

Added in: astro@3.5.0

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

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

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

`info` 옵션

타입: any

Added in: astro@3.6.0

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

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

`state` 옵션

타입: any

Added in: astro@3.6.0

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

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

`sourceElement` 옵션

타입: Element

Added in: astro@3.6.0

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

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

타입: boolean

Added in: astro@3.2.0

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

`transitionEnabledOnThisPage`

타입: boolean

Added in: astro@3.2.0

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

`getFallback()`

타입: () => 'none' | 'animate' | 'swap'

Added in: astro@3.6.0

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

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

`swapFunctions`

Added in: astro@4.15.0

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

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

`deselectScripts()`

타입: (newDocument: Document) => void

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

`swapRootAttributes()`

타입: (newDocument: Document) => void

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

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

`swapHeadElements()`

타입: (newDocument: Document) => void

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

`saveFocus()`

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

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

`swapBodyElement()`

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

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

라이프사이클 이벤트

`astro:before-preparation` 이벤트

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

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

info
sourceElement
navigationType
direction
from
to
formData
loader()

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

`astro:after-preparation` 이벤트

View Transitions를 사용하는 탐색에서 다음 페이지가 로드된 후 전송되는 이벤트입니다.

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

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

`astro:before-swap` 이벤트

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

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

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

info
sourceElement
navigationType
direction
from
to
viewTransition
swap()

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

`astro:after-swap` 이벤트

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

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

`astro:page-load` 이벤트

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

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

라이프사이클 이벤트 속성

Added in: astro@3.6.0

`info`

타입: URL

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

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

`sourceElement`

타입: Element | undefined

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

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

`newDocument`

타입: Document

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

`navigationType`

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

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

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

`direction`

타입: Direction

트랜지션 방향입니다.

forward: 기록의 다음 페이지 또는 새 페이지로 이동합니다.
back: 기록의 이전 페이지로 이동합니다.
다른 리스너가 설정했을 수 있는 기타 모든 항목.

`from`

타입: URL

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

`to`

타입: URL

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

`formData`

타입: FormData | undefined

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

이 속성을 설정하면 일반적인 GET 요청 대신 지정된 양식 데이터 객체를 콘텐츠로 하는 POST 요청이 to URL로 전송됩니다.

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

`loader()`

타입: () => Promise<void>

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

`viewTransition`

타입: ViewTransition

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

`swap()`

타입: () => void

문서 스왑 로직을 구현합니다.

사용자 지정 스왑 함수를 구현하는 방법에 대한 자세한 내용은 View Transitions 가이드를 참조하세요.

기본적으로 이 구현은 다음 함수를 순서대로 호출합니다:

deselectScripts()
swapRootAttributes()
swapHeadElements()
saveFocus()
swapBodyElement()

기여하기

커뮤니티

View Transitions API 참조

astro:transitions에서 가져오기

<ViewTransitions />

fade

slide

astro:transitions/client에서 가져오기

navigate()

history 옵션

formData 옵션

info 옵션

state 옵션

sourceElement 옵션

supportsViewTransitions

transitionEnabledOnThisPage

getFallback()

swapFunctions

deselectScripts()

swapRootAttributes()

swapHeadElements()

saveFocus()

swapBodyElement()

라이프사이클 이벤트

astro:before-preparation 이벤트

astro:after-preparation 이벤트

astro:before-swap 이벤트

astro:after-swap 이벤트

astro:page-load 이벤트

라이프사이클 이벤트 속성

info

sourceElement

newDocument

navigationType

direction

from

to

formData

loader()

viewTransition

swap()

`astro:transitions`에서 가져오기

`<ViewTransitions />`

`fade`

`slide`

`astro:transitions/client`에서 가져오기

`navigate()`

`history` 옵션

`formData` 옵션

`info` 옵션

`state` 옵션

`sourceElement` 옵션

`supportsViewTransitions`

`transitionEnabledOnThisPage`

`getFallback()`

`swapFunctions`

`deselectScripts()`

`swapRootAttributes()`

`swapHeadElements()`

`saveFocus()`

`swapBodyElement()`

`astro:before-preparation` 이벤트

`astro:after-preparation` 이벤트

`astro:before-swap` 이벤트

`astro:after-swap` 이벤트

`astro:page-load` 이벤트

`info`

`sourceElement`

`newDocument`

`navigationType`

`direction`

`from`

`to`

`formData`

`loader()`

`viewTransition`

`swap()`