Справочник API маршрутизатора View Transitions

Добавлено в: astro@3.0.0

Эти модули предоставляют функции для управления и взаимодействия с API View Transitions (переходов между представлениями) и клиентским маршрутизатором.

Информацию о функциях и примеры использования смотрите в нашем руководстве по View Transitions.

Импорт из `astro:transitions`

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

`<ClientRouter />`

Добавлено в: astro@5.0.0

Включите использование переходов (view transitions) на отдельных страницах, импортировав и добавив компонент маршрутизации <ClientRouter /> в <head> каждой желаемой страницы.

---
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>Моя домашняя страница</title>
    <ClientRouter />
  </head>
  <body>
    <h1>Добро пожаловать на мой сайт!</h1>
  </body>
</html>

Узнайте больше о том, как управлять маршрутизатором и добавлять директивы перехода к элементам страницы и компонентам.

Компонент <ClientRouter /> принимает следующие пропсы:

`fallback`

Тип: Fallback
По умолчанию: animate

Определяет стратегию отката (fallback) для использования в браузерах, которые не поддерживают API View Transitions.

`fade`

Тип: (opts: { duration?: string | number }) => TransitionDirectionalAnimations

Добавлено в: astro@3.0.0

Утилита для поддержки настройки длительности встроенной анимации fade (затухание).

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

<!-- Переход Fade с длительностью по умолчанию -->
<div transition:animate="fade" />

<!-- Переход Fade с длительностью 400 миллисекунд -->
<div transition:animate={fade({ duration: '0.4s' })} />

`slide`

Тип: (opts: { duration?: string | number }) => TransitionDirectionalAnimations

Добавлено в: astro@3.0.0

Утилита для поддержки настройки длительности встроенной анимации slide (скольжение).

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

<!-- Переход Slide с длительностью по умолчанию -->
<div transition:animate="slide" />

<!-- Переход Slide с длительностью 400 миллисекунд -->
<div transition:animate={slide({ duration: '0.4s' })} />

Импорт из `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

Выполняет навигацию по заданному href с использованием API View Transitions.

Сигнатура этой функции основана на функции navigate из API навигации браузера. Хотя она основана на API навигации, эта функция реализована поверх History API, чтобы позволить навигацию без перезагрузки страницы.

navigate() не выполняет очистку (санитизацию) параметра href. Очищайте пользовательский ввод, если используете его для определения URL для перехода.

опция `history`

Тип: 'auto' | 'push' | 'replace'
По умолчанию: 'auto'

Добавлено в: astro@3.2.0

Определяет, как эта навигация должна быть добавлена в историю браузера.

'push': маршрутизатор будет использовать history.pushState для создания новой записи в истории браузера.
'replace': маршрутизатор будет использовать history.replaceState для обновления URL без добавления новой записи в навигацию.
'auto' (по умолчанию): маршрутизатор попытается использовать history.pushState, но если переход на URL невозможен, текущий URL останется без изменений в истории браузера.

Эта опция следует опции history из API навигации браузера, но упрощена для случаев, которые могут возникнуть в проекте Astro.

опция `formData`

Тип: FormData

Добавлено в: astro@3.5.0

Объект FormData для запросов POST.

Когда эта опция предоставлена, запросы к целевой странице навигации будут отправлены как запрос POST с объектом данных формы в качестве содержимого.

Отправка HTML-формы с включенными переходами (view transitions) будет использовать этот метод вместо стандартной навигации с перезагрузкой страницы. Вызов этого метода позволяет запускать то же поведение программно.

опция `info`

Тип: any

Добавлено в: astro@3.6.0

Произвольные данные, которые будут включены в события astro:before-preparation и astro:before-swap, вызванные этой навигацией.

Эта опция имитирует опцию info из API навигации браузера.

опция `state`

Тип: any

Добавлено в: astro@3.6.0

Произвольные данные, которые будут связаны с объектом NavigationHistoryEntry, созданным этой навигацией. Эти данные затем могут быть извлечены с помощью функции history.getState из History API.

Эта опция имитирует опцию state из API навигации браузера.

опция `sourceElement`

Тип: Element

Добавлено в: astro@3.6.0

Элемент, который инициировал эту навигацию, если таковой имеется. Этот элемент будет доступен в следующих событиях:

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

Тип: boolean

Добавлено в: astro@3.2.0

Поддерживаются ли и включены ли переходы (view transitions) в текущем браузере.

`transitionEnabledOnThisPage()`

Тип: () => boolean

Добавлено в: astro@3.2.0

Включены ли на текущей странице переходы для клиентской навигации. Это можно использовать для создания компонентов, которые ведут себя по-разному, когда они используются на страницах с переходами.

`getFallback()`

Тип: () => Fallback
По умолчанию: animate

Добавлено в: astro@3.6.0

Возвращает стратегию отката для использования (animate по умолчанию) в браузерах, которые не поддерживают переходы.

Смотрите руководство по контролю отката (fallback) о том, как выбрать и настроить поведение.

`swapFunctions`

Тип: object

Добавлено в: astro@4.15.0

Объект, содержащий утилитарные функции, используемые для построения функции замены (swap function) Astro по умолчанию. Они могут быть полезны при создании пользовательской функции замены.

swapFunctions предоставляет следующие методы:

`deselectScripts()`

Тип: (newDocument: Document) => void

Помечает скрипты в новом документе, которые не должны выполняться. Эти скрипты уже находятся в текущем документе и не помечены для повторного выполнения с помощью data-astro-rerun.

`swapRootAttributes()`

Тип: (newDocument: Document) => void

Меняет местами атрибуты между корневыми элементами документов, например атрибут lang. Сюда также входят внутренние атрибуты, внедряемые Astro, такие как data-astro-transition, который делает направление перехода доступным для CSS-правил, сгенерированных Astro.

При создании пользовательской функции замены важно вызывать эту функцию, чтобы не нарушить анимацию переходов.

`swapHeadElements()`

Тип: (newDocument: Document) => void

Удаляет каждый элемент из <head> текущего документа, который не сохраняется в новом документе. Затем добавляет все новые элементы из <head> нового документа в <head> текущего документа.

`saveFocus()`

Тип: () => () => void

Сохраняет элемент, находящийся в фокусе на текущей странице, и возвращает функцию, которая при вызове (если сфокусированный элемент был сохранен) возвращает фокус на него.

`swapBodyElement()`

Тип: (newBody: Element, oldBody: Element) => void

Заменяет старое тело (body) новым. Затем проходит через каждый элемент в старом теле, который должен быть сохранен и имеет соответствующий элемент в новом теле, и меняет старый элемент обратно на его место.

Устаревшие импорты

Следующие импорты запланированы к удалению в v6. Вы все еще можете использовать их в своем проекте, но, возможно, вы предпочтете обновить свой код сейчас.

`isTransitionBeforePreparationEvent()`

Тип: (value: any) => boolean

Добавлено в: astro@3.6.0

Определяет, соответствует ли данное значение TransitionBeforePreparationEvent. Это может быть полезно, когда вам нужно сузить тип события в слушателе событий.

---
---

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

  function listener(event: Event) {
    const setting = isTransitionBeforePreparationEvent(event) ? 1 : 2;
    /* сделать что-то с setting */
  }

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

`isTransitionBeforeSwapEvent()`

Тип: (value: any) => boolean

Добавлено в: astro@3.6.0

Определяет, соответствует ли данное значение TransitionBeforeSwapEvent. Это может быть полезно, когда вам нужно сузить тип события в слушателе событий.

---
---

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

  function listener(event: Event) {
    const setting = isTransitionBeforeSwapEvent(event) ? 1 : 2;
    /* сделать что-то с setting */
  }

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

`TRANSITION_BEFORE_PREPARATION`

Тип: 'astro:before-preparation'

Добавлено в: astro@3.6.0

Константа, позволяющая избежать написания имени события astro:before-preparation простым текстом при определении события.

---
---

<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 простым текстом при определении события.

`TRANSITION_BEFORE_SWAP`

Тип: 'astro:before-swap'

Добавлено в: astro@3.6.0

Константа, позволяющая избежать написания имени события astro:before-swap простым текстом при определении события.

`TRANSITION_AFTER_SWAP`

Тип: 'astro:after-swap'

Добавлено в: astro@3.6.0

Константа, позволяющая избежать написания имени события astro:after-swap простым текстом при определении события.

`TRANSITION_PAGE_LOAD`

Тип: 'astro:page-load'

Добавлено в: astro@3.6.0

Константа, позволяющая избежать написания имени события astro:page-load простым текстом при определении события.

Типы `astro:transitions/client`

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

`Direction`

Тип: 'forward' | 'back'

Добавлено в: astro@3.2.0

Объединение направлений анимации:

forward: навигация на следующую страницу в истории или на новую страницу.
back: навигация на предыдущую страницу в истории.

`Fallback`

Тип: 'none' | 'animate' | 'swap'

Добавлено в: astro@3.2.0

Объединение стратегий отката для использования в браузерах, которые не поддерживают переходы:

animate: Astro будет симулировать переходы с использованием пользовательских атрибутов перед обновлением содержимого страницы.
swap: Astro не будет пытаться анимировать страницу. Вместо этого старая страница будет немедленно заменена новой.
none: Astro не будет выполнять никаких анимированных переходов страницы. Вместо этого вы получите полную навигацию по страницам в неподдерживающих браузерах.

Узнайте больше о контроле стратегии отката с помощью ClientRouter.

`NavigationTypeString`

Тип: 'push' | 'replace' | 'traverse'

Добавлено в: astro@3.6.0

Объединение поддерживаемых событий навигации по истории.

`TransitionBeforePreparationEvent`

Тип: Event

Добавлено в: astro@3.6.0

Представляет событие astro:before-preparation. Это может быть полезно для типизации события, полученного слушателем.

`TransitionBeforeSwapEvent`

Тип: Event

Добавлено в: astro@3.6.0

Представляет событие astro:before-swap. Это может быть полезно для типизации события, полученного слушателем.

События жизненного цикла

событие `astro:before-preparation`

Тип: TransitionBeforePreparationEvent

Добавлено в: astro@3.6.0

Событие, отправляемое в начале навигации с использованием маршрутизатора View Transitions. Это событие происходит до выполнения какого-либо запроса и изменения состояния браузера.

Это событие имеет атрибуты:

info
sourceElement
navigationType
direction
from
to
formData
loader()

Узнайте больше о том, как использовать это событие, в руководстве по View Transitions.

событие `astro:after-preparation`

Тип: Event

Добавлено в: astro@3.6.0

Событие, отправляемое после того, как следующая страница в навигации с использованием маршрутизатора View Transitions загружена.

У этого события нет атрибутов.

Узнайте больше о том, как использовать это событие, в руководстве по View Transitions.

событие `astro:before-swap`

Тип: TransitionBeforeSwapEvent

Добавлено в: astro@3.6.0

Событие, отправляемое после того, как следующая страница была разобрана, подготовлена и связана с документом при подготовке к переходу, но до того, как какой-либо контент будет заменен между документами.

Это событие нельзя отменить. Вызов preventDefault() ничего не даст.

Это событие имеет атрибуты:

info
sourceElement
navigationType
direction
from
to
viewTransition
swap()

Узнайте больше о том, как использовать это событие, в руководстве по View Transitions.

событие `astro:after-swap`

Тип: Event

Событие, отправляемое после того, как содержимое страницы было заменено, но до завершения перехода.

Запись в истории и позиция прокрутки уже обновлены, когда срабатывает это событие.

событие `astro:page-load`

Тип: Event

Событие, отправляемое после завершения загрузки страницы, будь то навигация с использованием переходов (view transitions) или нативная для браузера.

Когда на странице включены переходы, код, который обычно выполняется по DOMContentLoaded, должен быть изменен для выполнения по этому событию.

Атрибуты событий жизненного цикла

Добавлено в: astro@3.6.0

Следующие атрибуты являются общими для событий astro:before-preparation и astro:before-swap, за исключением некоторых, которые доступны только в одном или другом.

`info`

Тип: any

Произвольные данные, определенные во время навигации.

Это буквальное значение, переданное в опции info функции navigate().

`sourceElement`

Тип: Element | undefined

Элемент, вызвавший навигацию. Это может быть, например, элемент <a>, по которому кликнули.

При использовании функции navigate() это будет элемент, указанный в вызове.

`newDocument`

Тип: Document

Документ для следующей страницы в навигации. Содержимое этого документа будет заменено на место содержимого текущего документа.

`navigationType`

Тип: NavigationTypeString

Какой вид навигации по истории происходит.

push: создается новая NavigationHistoryEntry для новой страницы.
replace: текущая NavigationHistoryEntry заменяется записью для новой страницы.
traverse: NavigationHistoryEntry не создается. Позиция в истории меняется. Направление обхода указано в атрибуте direction.

`direction`

Тип: string

Направление перехода:

В событии astro:before-preparation это может быть использовано для определения пользовательских направлений. Свойство доступно для записи и принимает любую строку.
В событии astro:before-swap это может быть использовано для получения направления перехода. Свойство доступно только для чтения, и его значением может быть предопределенное Direction или любая строка, которую мог установить слушатель события astro:before-preparation.

`from`

Тип: URL

URL страницы, инициирующей навигацию.

`to`

Тип: URL

URL страницы, на которую осуществляется переход. Это свойство можно изменить, значение в конце жизненного цикла будет использовано в NavigationHistoryEntry для следующей страницы.

`formData`

Тип: FormData | undefined
Доступно в: событии astro:before-preparation

Если установлено, запрос POST будет отправлен на URL to с данным объектом FormData в качестве содержимого вместо обычного запроса GET.

При отправке HTML-формы с включенными переходами это поле автоматически устанавливается в данные формы. При использовании функции navigate() это значение совпадает с указанным в опциях.

`loader()`

Тип: () => Promise<void>
Доступно в: событии astro:before-preparation

Реализация следующей фазы в навигации (загрузка следующей страницы). Эту реализацию можно переопределить для добавления дополнительного поведения.

`viewTransition`

Тип: ViewTransition
Доступно в: событии astro:before-swap

Объект перехода (view transition), используемый в этой навигации. В браузерах, которые не поддерживают API View Transitions, это объект, реализующий тот же API для удобства, но без интеграции с DOM.

`swap()`

Тип: () => void
Доступно в: событии astro:before-swap

Вызывает логику замены документа по умолчанию. По умолчанию эта реализация будет вызывать следующие функции в порядке:

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

Узнайте больше о создании пользовательской функции замены в руководстве по View Transitions.

Справочник API маршрутизатора View Transitions

Импорт из astro:transitions

<ClientRouter />

fallback

fade

slide

Импорт из astro:transitions/client

navigate()

опция history

опция formData

опция info

опция state

опция sourceElement

supportsViewTransitions

transitionEnabledOnThisPage()

getFallback()

swapFunctions

deselectScripts()

swapRootAttributes()

swapHeadElements()

saveFocus()

swapBodyElement()

Устаревшие импорты

isTransitionBeforePreparationEvent()

isTransitionBeforeSwapEvent()

TRANSITION_BEFORE_PREPARATION

TRANSITION_AFTER_PREPARATION

TRANSITION_BEFORE_SWAP

TRANSITION_AFTER_SWAP

TRANSITION_PAGE_LOAD

Типы astro:transitions/client

Direction

Fallback

NavigationTypeString

TransitionBeforePreparationEvent

TransitionBeforeSwapEvent

События жизненного цикла

событие 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`

`<ClientRouter />`

`fallback`

`fade`

`slide`

Импорт из `astro:transitions/client`

`navigate()`

опция `history`

опция `formData`

опция `info`

опция `state`

опция `sourceElement`

`supportsViewTransitions`

`transitionEnabledOnThisPage()`

`getFallback()`

`swapFunctions`

`deselectScripts()`

`swapRootAttributes()`

`swapHeadElements()`

`saveFocus()`

`swapBodyElement()`

`isTransitionBeforePreparationEvent()`

`isTransitionBeforeSwapEvent()`

`TRANSITION_BEFORE_PREPARATION`

`TRANSITION_AFTER_PREPARATION`

`TRANSITION_BEFORE_SWAP`

`TRANSITION_AFTER_SWAP`

`TRANSITION_PAGE_LOAD`

Типы `astro:transitions/client`

`Direction`

`Fallback`

`NavigationTypeString`

`TransitionBeforePreparationEvent`

`TransitionBeforeSwapEvent`

событие `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()`