Referencia de la API del Router de View Transitions

Añadido en: astro@3.0.0

Estos módulos proporcionan funciones para controlar e interactuar con la API de View Transitions y el router del lado del cliente.

Para características y ejemplos de uso, consulta nuestra guía de View Transitions.

Importaciones desde `astro:transitions`

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

`<ClientRouter />`

Añadido en: astro@5.0.0

Activa el uso de view transitions en páginas individuales importando y añadiendo el componente de routing <ClientRouter /> al <head> de cada página deseada.

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

Ver más sobre cómo controlar el router y añadir directivas de transición a elementos de página y componentes.

El componente <ClientRouter /> acepta las siguientes props:

`fallback`

Type: Fallback
Default: animate

Define la estrategia de fallback a usar para navegadores que no soportan la View Transitions API.

`fade`

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

Añadido en: astro@3.0.0

Función utilidad para soportar la personalización de la duración de la animación fade integrada.

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

<!-- Fade transition with the default duration -->
<div transition:animate="fade" />

<!-- Fade transition with a duration of 400 milliseconds -->
<div transition:animate={fade({ duration: '0.4s' })} />

`slide`

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

Añadido en: astro@3.0.0

Función utilidad para soportar la personalización de la duración de la animación slide integrada.

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

<!-- Slide transition with the default duration -->
<div transition:animate="slide" />

<!-- Slide transition with a duration of 400 milliseconds -->
<div transition:animate={slide({ duration: '0.4s' })} />

Importaciones desde `astro:transitions/client`

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

`navigate()`

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

Añadido en: astro@3.2.0

Ejecuta una navegación al href dado usando la View Transitions API.

La firma de esta función está basada en la función navigate de la Navigation API del navegador. Aunque está basada en la Navigation API, esta función está implementada sobre la History API para permitir navegación sin recargar la página.

navigate() no realiza sanitización del parámetro href. Sanea la entrada del usuario si la usas para determinar la URL a la que navegar.

opción `history`

Type: 'auto' | 'push' | 'replace'
Default: 'auto'

Añadido en: astro@3.2.0

Define cómo esta navegación debería añadirse al historial del navegador.

'push': el router usará history.pushState para crear una nueva entrada en el historial del navegador.
'replace': el router usará history.replaceState para actualizar la URL sin añadir una nueva entrada a la navegación.
'auto' (por defecto): el router intentará history.pushState, pero si la URL no puede ser transitada, la URL actual permanecerá sin cambios en el historial del navegador.

Esta opción sigue la opción history de la Navigation API del navegador pero simplificada para los casos que pueden ocurrir en un proyecto de Astro.

opción `formData`

Type: FormData

Añadido en: astro@3.5.0

Un objeto FormData para solicitudes POST.

Cuando se proporciona esta opción, las solicitudes a la página de destino de navegación se enviarán como una solicitud POST con el objeto de datos del formulario como contenido.

Enviar un formulario HTML con view transitions habilitadas usará este método en lugar de la navegación por defecto con recarga de página. Llamar a este método permite desencadenar el mismo comportamiento programáticamente.

opción `info`

Type: any

Añadido en: astro@3.6.0

Datos arbitrarios a incluir en los eventos astro:before-preparation y astro:before-swap causados por esta navegación.

Esta opción imita la opción info de la Navigation API del navegador.

opción `state`

Type: any

Añadido en: astro@3.6.0

Datos arbitrarios a asociar con el objeto NavigationHistoryEntry creado por esta navegación. Estos datos pueden luego recuperarse usando la función history.getState de la History API.

Esta opción imita la opción state de la Navigation API del navegador.

opción `sourceElement`

Type: Element

Añadido en: astro@3.6.0

El elemento que desencadenó esta navegación, si lo hay. Este elemento estará disponible en los siguientes eventos:

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

Type: boolean

Añadido en: astro@3.2.0

Si las view transitions están soportadas y habilitadas en el navegador actual.

`transitionEnabledOnThisPage()`

Type: () => boolean

Añadido en: astro@3.2.0

Si la página actual tiene view transitions habilitadas para navegación del lado del cliente. Esto puede usarse para hacer componentes que se comporten de manera diferente cuando se usan en páginas con view transitions.

`getFallback()`

Type: () => Fallback
Default: animate

Añadido en: astro@3.6.0

Devuelve la estrategia de fallback a usar (animate por defecto) en navegadores que no soportan view transitions.

Ver la guía sobre Control de fallback para cómo elegir y configurar el comportamiento de fallback.

`swapFunctions`

Type: object

Añadido en: astro@4.15.0

Un objeto que contiene las funciones utilidad usadas para construir la función de swap por defecto de Astro. Estas pueden ser útiles al construir una función de swap personalizada.

swapFunctions proporciona los siguientes métodos:

`deselectScripts()`

Type: (newDocument: Document) => void

Marca los scripts en el nuevo documento que no deberían ejecutarse. Esos scripts ya están en el documento actual y no están marcados para re-ejecución usando data-astro-rerun.

`swapRootAttributes()`

Type: (newDocument: Document) => void

Intercambia los atributos entre las raíces del documento, como el atributo lang. Esto también incluye atributos internos inyectados por Astro como data-astro-transition, que hace que la dirección de la transición esté disponible para las reglas CSS generadas por Astro.

Al hacer una función de swap personalizada, es importante llamar a esta función para no romper las animaciones de la view transition.

`swapHeadElements()`

Type: (newDocument: Document) => void

Elimina cada elemento del <head> del documento actual que no se persiste al nuevo documento. Luego añade todos los elementos nuevos del <head> del nuevo documento al <head> del documento actual.

`saveFocus()`

Type: () => () => void

Almacena el elemento en foco en la página actual y devuelve una función que cuando se llama, si el elemento en foco fue persistido, devuelve el foco a él.

`swapBodyElement()`

Type: (newBody: Element, oldBody: Element) => void

Reemplaza el body antiguo con el body nuevo. Luego, recorre cada elemento en el body antiguo que debería ser persistido y tiene un elemento coincidente en el body nuevo y vuelve a intercambiar el elemento antiguo en su lugar.

Tipos de `astro:transitions/client`

import type {
  Direction,
  Fallback,
  NavigationTypeString,
  Options,
  TransitionBeforePreparationEvent,
  TransitionBeforeSwapEvent,
} from 'astro:transitions/client';

`Direction`

Type: 'forward' | 'back'

Añadido en: astro@3.2.0

Una unión de direcciones de animación:

forward: navegando a la siguiente página en el historial o a una nueva página.
back: navegando a la página anterior en el historial.

`Fallback`

Type: 'none' | 'animate' | 'swap'

Añadido en: astro@3.2.0

Una unión de estrategias de fallback para usar en navegadores que no soportan view transitions:

animate: Astro simulará view transitions usando atributos personalizados antes de actualizar el contenido de la página.
swap: Astro no intentará animar la página. En su lugar, la página antigua será reemplazada inmediatamente por la nueva.
none: Astro no hará ninguna transición de página animada. En su lugar, obtendrás navegación de página completa en navegadores no soportados.

Aprende más sobre controlar la estrategia de fallback con el ClientRouter.

`NavigationTypeString`

Type: 'push' | 'replace' | 'traverse'

Añadido en: astro@3.6.0

Una unión de eventos de navegación del historial soportados.

`TransitionBeforePreparationEvent`

Type: Event

Añadido en: astro@3.6.0

Representa un evento astro:before-preparation. Esto puede ser útil para tipar el evento recibido por un listener:

---
---

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

  function listener(event: TransitionBeforePreparationEvent) {
    /* do something */
  }

  document.addEventListener("astro:before-preparation", listener);
</script>

`TransitionBeforeSwapEvent`

Type: Event

Añadido en: astro@3.6.0

Representa un evento astro:before-swap. Esto puede ser útil para tipar el evento recibido por un listener:

---
---

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

  function listener(event: TransitionBeforeSwapEvent) {
    /* do something */
  }

  document.addEventListener("astro:before-swap", listener);
</script>

Eventos del lifecycle

evento `astro:before-preparation`

Type: TransitionBeforePreparationEvent

Añadido en: astro@3.6.0

Un evento despachado al inicio de una navegación usando el router de View Transitions. Este evento ocurre antes de que se haga cualquier solicitud y antes de que cambie cualquier estado del navegador.

Este evento tiene los atributos:

info
sourceElement
navigationType
direction
from
to
formData
loader()

Lee más sobre cómo usar este evento en la guía de View Transitions.

evento `astro:after-preparation`

Type: Event

Añadido en: astro@3.6.0

Un evento despachado después de que la siguiente página en una navegación usando el router de View Transitions es cargada.

Este evento no tiene atributos.

Lee más sobre cómo usar este evento en la guía de View Transitions.

evento `astro:before-swap`

Type: TransitionBeforeSwapEvent

Añadido en: astro@3.6.0

Un evento despachado después de que la siguiente página es parseada, preparada y enlazada a un documento en preparación para la transición pero antes de que cualquier contenido sea intercambiado entre los documentos.

Este evento no puede cancelarse. Llamar a preventDefault() es un no-op.

Este evento tiene los atributos:

info
sourceElement
navigationType
direction
from
to
viewTransition
swap()

Lee más sobre cómo usar este evento en la guía de View Transitions.

evento `astro:after-swap`

Type: Event

Un evento despachado después de que los contenidos de la página hayan sido intercambiados pero antes de que la view transition termine.

La entrada del historial y la posición de scroll ya han sido actualizadas cuando este evento es desencadenado.

evento `astro:page-load`

Type: Event

Un evento despachado después de que una página completa la carga, ya sea desde una navegación usando view transitions o nativa del navegador.

Cuando las view transitions están habilitadas en la página, el código que normalmente se ejecutaría en DOMContentLoaded debería cambiarse para ejecutarse en este evento.

Atributos de los eventos del ciclo de vida

Añadido en: astro@3.6.0

Los siguientes atributos son comunes a los eventos astro:before-preparation y astro:before-swap, excepto algunos que solo están disponibles con uno u otro.

`info`

Type: any

Datos arbitrarios definidos durante la navegación.

Este es el valor literal pasado en la opción info de la función navigate().

`sourceElement`

Type: Element | undefined

El elemento que desencadenó la navegación. Puede ser, por ejemplo, un elemento <a> que fue clicado.

Al usar la función navigate(), este será el elemento especificado en la llamada.

`newDocument`

Type: Document

El documento de la siguiente página en la navegación. Los contenidos de este documento serán intercambiados en lugar de los contenidos del documento actual.

`navigationType`

Type: NavigationTypeString

Qué tipo de navegación del historial está ocurriendo.

push: se está creando una nueva NavigationHistoryEntry para la nueva página.
replace: la NavigationHistoryEntry actual está siendo reemplazada por una entrada para la nueva página.
traverse: no se crea ninguna NavigationHistoryEntry. La posición en el historial está cambiando. La dirección del recorrido se da en el atributo direction.

`direction`

Type: string

La dirección de la transición:

En un evento astro:before-preparation, esto puede usarse para definir direcciones personalizadas. La propiedad es escribible y acepta cualquier string.
En un evento astro:before-swap, esto puede usarse para recuperar la dirección de la transición. La propiedad es de solo lectura y su valor puede ser una Direction predefinida o cualquier string que un listener del evento astro:before-preparation pueda haber establecido.

`from`

Type: URL

La URL de la página que inicia la navegación.

`to`

Type: URL

La URL de la página a la que se está navegando. Esta propiedad puede modificarse, el valor al final del ciclo de vida será usado en el NavigationHistoryEntry para la siguiente página.

`formData`

Type: FormData | undefined
Available in: evento astro:before-preparation

Cuando se establece, se enviará una solicitud POST a la URL to con el objeto FormData dado como contenido en lugar de la solicitud GET normal.

Al enviar un formulario HTML con view transitions habilitadas, este campo se establece automáticamente con los datos del formulario. Al usar la función navigate(), este valor es el mismo que el dado en las opciones.

`loader()`

Type: () => Promise<void>
Available in: evento astro:before-preparation

Implementación de la siguiente fase en la navegación (cargando la siguiente página). Esta implementación puede sobrescribirse para añadir comportamiento extra.

`viewTransition`

Type: ViewTransition
Available in: evento astro:before-swap

El objeto view transition usado en esta navegación. En navegadores que no soportan la View Transitions API, este es un objeto que implementa la misma API por conveniencia pero sin la integración del DOM.

`swap()`

Type: () => void
Available in: evento astro:before-swap

Llama a la lógica de swap de documento por defecto. Por defecto, esta implementación llamará a las siguientes funciones en orden:

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

Lee más sobre construir una función de swap personalizada en la guía de View Transitions.

Contribuir Comunidad Patrocinar

Referencia de la API del Router de View Transitions

Importaciones desde astro:transitions

<ClientRouter />

fallback

fade

slide

Importaciones desde astro:transitions/client

navigate()

opción history

opción formData

opción info

opción state

opción sourceElement

supportsViewTransitions

transitionEnabledOnThisPage()

getFallback()

swapFunctions

deselectScripts()

swapRootAttributes()

swapHeadElements()

saveFocus()

swapBodyElement()

Tipos de astro:transitions/client

Direction

Fallback

NavigationTypeString

TransitionBeforePreparationEvent

TransitionBeforeSwapEvent

Eventos del lifecycle

evento astro:before-preparation

evento astro:after-preparation

evento astro:before-swap

evento astro:after-swap

evento astro:page-load

Atributos de los eventos del ciclo de vida

info

sourceElement

newDocument

navigationType

direction

from

to

formData

loader()

viewTransition

swap()

Importaciones desde `astro:transitions`

`<ClientRouter />`

`fallback`

`fade`

`slide`

Importaciones desde `astro:transitions/client`

`navigate()`

opción `history`

opción `formData`

opción `info`

opción `state`

opción `sourceElement`

`supportsViewTransitions`

`transitionEnabledOnThisPage()`

`getFallback()`

`swapFunctions`

`deselectScripts()`

`swapRootAttributes()`

`swapHeadElements()`

`saveFocus()`

`swapBodyElement()`

Tipos de `astro:transitions/client`

`Direction`

`Fallback`

`NavigationTypeString`

`TransitionBeforePreparationEvent`

`TransitionBeforeSwapEvent`

evento `astro:before-preparation`

evento `astro:after-preparation`

evento `astro:before-swap`

evento `astro:after-swap`

evento `astro:page-load`

`info`

`sourceElement`

`newDocument`

`navigationType`

`direction`

`from`

`to`

`formData`

`loader()`

`viewTransition`

`swap()`