视图过渡路由 API 参考

添加于： astro@3.0.0

此模块提供了一些函数，用于控制和与视图过渡 API 和客户端路由进行交互。

从 `astro:transitions` 导入

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

`<ClientRouter />`

添加于： astro@5.0.0

通过将 <ClientRouter /> 路由组件导入并添加到每个所需页面的 <head> 部分，以选择在各个页面上使用视图过渡动画。

---
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>我的首页</title>
    <ClientRouter />
  </head>
  <body>
    <h1>欢迎来到我的网站！</h1>
  </body>
</html>

查看有关如何控制路由器以及添加过渡指令到页面元素和组件的更多信息。

<ClientRouter /> 组件接受以下参数：

`fallback`

类型： Fallback
默认值： animate

定义在不支持视图过渡API 的浏览器上使用的回退策略。

`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`

类型： (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` 导入

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` 选项

类型：'auto' | 'push' | 'replace'
默认值：'auto'

添加于： astro@3.2.0

定义了如何将此导航添加到浏览器历史记录中。

'push'：路由将使用 history.pushState 在浏览器历史记录中创建一个新条目。
'replace'：路由将使用 history.replaceState 更新 URL，而不会在导航中添加新条目。
'auto'（默认）：路由将尝试 history.pushState，但如果无法进行过渡，则当前 URL 将保持不变，浏览器历史记录不会发生变化。

此选项遵循浏览器 Navigation API 中的 history 选项，但简化了在 Astro 项目中可能发生的情况。

`formData` 选项

类型：FormData

添加于： astro@3.5.0

一个 FormData 对象，用于 POST 请求。

当提供此选项时，导航目标页面的请求将以 POST 请求的形式发送，内容为表单数据对象。

当提交一个带有视图过渡的 HTML 表单时，将使用此方法代替默认的页面重新加载导航。调用此方法允许以编程方式触发相同的行为。

`info` 选项

类型：any

添加于： astro@3.6.0

与导航相关的 astro:before-preparation 和 astro:before-swap 事件中包含的任意数据。

此选项模仿了浏览器 Navigation API 中的 info 选项。

`state` 选项

类型：any

添加于： astro@3.6.0

与导航相关的 NavigationHistoryEntry 对象中关联的任意数据。此数据可以通过 history.getState 函数从 History API 中检索。

此选项模仿了浏览器 Navigation API 中的 state 选项。

`sourceElement` 选项

类型：Element

添加于： astro@3.6.0

此导航的触发元素，如果有的话。此元素将在以下事件中可用：

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

类型：boolean

添加于： astro@3.2.0

当前浏览器是否支持并启用视图过渡。

`transitionEnabledOnThisPage()`

类型：() => boolean

添加于： astro@3.2.0

当前页面是否启用了视图过渡以进行客户端导航。这可以用于使组件在视图过渡页面上的行为有所不同。

`getFallback`

类型： () => Fallback
默认值： animate

添加于： astro@3.6.0

返回在浏览器不支持视图过渡时使用的回退策略（默认 animate）。

有关如何选择和配置回退行为的详细信息，请参阅回退控制指南。

`swapFunctions`

类型： object

添加于： astro@4.15.0

一个对象，其中包含了用于构建 Astro 默认交换函数的工具类函数。这些函数在构建自定义交换函数时非常有用。

swapFunctions 提供了以下方法：

`deselectScripts()`

类型： (newDocument: Document) => void

标记在新的 document 中不应执行的脚本。这些脚本已经在当前 document 中，并且没有使用 data-astro-rerun 标记为重新执行。

`swapRootAttributes()`

类型：(newDocument: Document) => void

在 document 根节点之间交换属性，如 lang 属性。这也包括 Astro 注入的内部属性，如 data-astro-transition，这使得过渡方向可用于 Astro 生成的 CSS 规则。

在构建自定义交换函数时，重要的是调用此函数，以避免破坏视图过渡的动画。

`swapHeadElements()`

类型：(newDocument: Document) => void

从当前 document 的 <head> 中删除所有未持久化到新 document 的元素。然后将新 document 的 <head> 中的所有新元素附加到当前 document 的 <head>。

`saveFocus()`

类型：() => () => void

在当前页面上存储聚焦的元素，并返回一个函数，当调用时，如果聚焦的元素被持久化，则将焦点返回给该元素。

`swapBodyElement()`

类型：(newBody: Element, oldBody: Element) => void

用新 document 的 body 替换旧的 body。然后，遍历旧 body 中应持久化的每个元素，并在新 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;
    /* 对设置进行一些操作 */
  }

  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;
    /* 对设置进行一些操作 */
  }

  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 事件名称。

---
---

<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 事件名称。

---
---

<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 事件名称。

---
---

<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 事件名称。

---
---

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

  document.addEventListener(TRANSITION_PAGE_LOAD, () => {
    /* 监听逻辑 */
  });
</script>

`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 事件。这对于为监听器接收到的事件指定类型很有用：

---
---

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

  function listener(event: TransitionBeforePreparationEvent) {
    /* 业务逻辑 */
  }

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

`TransitionBeforeSwapEvent`

类型： Event

添加于： astro@3.6.0

表示一个 astro:before-swap 事件。这对于为监听器接收到的事件指定类型很有用：

---
---

<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` 事件

类型： TransitionBeforePreparationEvent

添加于： astro@3.6.0

使用视图过渡路由开始导航时触发的事件。此事件发生在任何请求之前，并且不会更改任何浏览器状态。

此事件具有以下属性：

info
sourceElement
navigationType
direction
from
to
formData
loader()

有关如何使用此事件的详细信息，请参阅视图过渡指南。

`astro:after-preparation` 事件

类型： Event

添加于： astro@3.6.0

使用视图过渡路由加载导航中的下一个页面后触发的事件。

此事件没有属性。

有关如何使用此事件的详细信息，请参阅视图过渡指南。

`astro:before-swap` 事件

类型： TransitionBeforeSwapEvent

添加于： astro@3.6.0

在视图过渡中导航的下一个页面解析、准备并链接到 document 后，但在任何内容在 document 之间交换之前触发的事件。

此事件不能取消。调用 preventDefault() 是无效的。

此事件具有以下属性：

info
sourceElement
navigationType
direction
from
to
viewTransition
swap

有关如何使用此事件的详细信息，请参阅视图过渡指南。

`astro:after-swap` 事件

类型： Event

在视图过渡中导航的下一个页面内容交换后，但在视图过渡结束之前触发的事件。

在触发此事件时，历史记录条目和滚动位置已经更新。

`astro:page-load` 事件

类型： Event

在页面完成加载后触发的事件，无论是通过视图过渡导航还是浏览器原生导航。

当视图过渡在页面上启用时，通常在 DOMContentLoaded 上执行的代码应更改为在此事件上执行。

生命周期事件属性

添加于： astro@3.6.0

以下属性在 astro:before-preparation 和 astro:before-swap 事件中是通用的，但有些属性仅在其中一个事件中可用。

`info`

类型：any

在导航期间定义的任意数据。

这是在 navigate() 函数的 info 选项中传递的文字值。

`sourceElement`

类型：Element | undefined

触发导航的元素。例如，这可以是点击的 <a> 元素。

当使用 navigate() 函数时，这将是调用中指定的元素。

`newDocument`

类型：Document

导航中下一个页面的 document。此 document 的内容将替换当前 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 事件

设置后，将向 [to URL] 发送一个 POST 请求，并以给定的 FormData 对象作为内容，而不是常规的 GET 请求。

当提交一个带有视图过渡的 HTML 表单时，此字段会自动设置为表单中的数据。当使用 navigate() 函数时，此值与给定的选项相同。

`loader`

类型：() => Promise<void>
可用于： astro:before-preparation 事件

在导航过程中下个阶段的实现（加载下一个页面）。此实现可以覆盖以添加额外的行为。

`viewTransition`

类型：ViewTransition
可用于： astro:before-swap 事件

在导航过程中使用的视图过渡对象。在浏览器不支持视图过渡 API 的情况下，这是一个对象，实现了相同的 API 以方便使用，但没有 DOM 集成。

`swap`

类型：() => void
可用于： astro:before-swap 事件

调用默认的文档替换逻辑。默认情况下，此实现将按以下顺序调用这些函数：

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

有关如何构建自定义交换函数的详细信息，请参阅视图过渡指南。

贡献社区赞助

视图过渡路由 API 参考

从 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`