视图转换路由器 API 参考

添加于： astro@3.0.0

这些模块提供了控制视图转换 API 和客户端路由并与之交互的函数。

从 `astro:transitions` 导入

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

`<ClientRouter />`

添加于： astro@3.0.0

通过导入 <ClientRouter /> 路由组件并将其添加到每个所需页面的 <head> 中，来选择在单个页面上使用视图转换。

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

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

`fade`

类型： (opts: { duration?: string | number }) => TransitionDirectionalAnimations

添加于： astro@3.0.0

用于支持自定义内置 fade 动画持续时间的实用函数。

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

类型： (opts: { duration?: string | number }) => TransitionDirectionalAnimations

添加于： astro@3.0.0

用于支持自定义内置 slide 动画持续时间的实用函数。

---
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' })} />

从 `astro:transitions/client` 导入

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

`navigate()`

类型： (href: string, options?: Options) => void

添加于： astro@3.2.0

一个使用视图转换 API 执行到给定 href 的导航的函数。

此函数签名基于浏览器导航 API 的 navigate 函数。尽管基于导航 API，但此函数是在History API之上实现的，以允许在不重新加载页面的情况下进行导航。

`history` 选项

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

添加于： astro@3.2.0

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

'push'：路由器将使用 history.pushState 在浏览器历史记录中创建一个新条目。
'replace'：路由器将使用 history.replaceState 更新 URL，而不会在导航中添加新条目。
'auto' (默认值): 路由器将尝试使用 history.pushState，但如果 URL 无法转换，当前 URL 将保持不变，浏览器历史记录也不会有任何更改。

此选项遵循浏览器导航 API 的 history 选项，但为 Astro 项目中可能发生的情况进行了简化。

`formData` 选项

类型： FormData

新增于： astro@3.5.0

用于 POST 请求的 FormData 对象。

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

在启用视图转换的情况下提交 HTML 表单将使用此方法，而不是使用页面重新加载的默认导航。调用此方法允许以编程方式触发相同的行为。

`info` 选项

类型： any

添加于： astro@3.6.0

要包含在此导航引起的 astro:before-preparation 和 astro:before-swap 事件中的任意数据。

此选项模仿了浏览器导航 API 的 info 选项。

`state` 选项

类型： any

添加于： astro@3.6.0

与此导航创建的 NavitationHistoryEntry 对象关联的任意数据。然后可以使用 History API 中的 history.getState 函数检索此数据。

此选项模仿了浏览器导航 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()`

类型： () => 'none' | 'animate' | 'swap'

添加于： astro@3.6.0

返回在不支持视图转换的浏览器中使用的回退策略。

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

`swapFunctions`

新增于： astro@4.15.0

一个包含用于构建 Astro 默认交换函数的实用函数的对象。这些在构建自定义交换函数时非常有用。

swapFunctions 提供以下方法

`deselectScripts()`

类型： (newDocument: Document) => void

标记新文档中不应执行的脚本。这些脚本已存在于当前文档中，并且未使用 data-astro-rerun 标记为重新执行。

`swapRootAttributes()`

类型： (newDocument: Document) => void

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

在创建自定义交换函数时，调用此函数非常重要，以免破坏视图转换的动画。

`swapHeadElements()`

类型： (newDocument: Document) => void

从当前文档的 <head> 中移除所有未持久化到新文档的元素。然后将新文档 <head> 中的所有新元素追加到当前文档的 <head> 中。

`saveFocus()`

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

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

`swapBodyElement()`

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

用新 body 替换旧 body。然后，遍历旧 body 中应持久化并在新 body 中有匹配元素的每个元素，并将旧元素交换回原位。

生命周期事件

`astro:before-preparation` 事件

在使用视图转换路由器进行导航开始时派发的事件。此事件发生在发出任何请求和更改任何浏览器状态之前。

此事件具有以下属性

info
sourceElement
navigationType
direction
from
to
formData
loader()

在视图转换指南中阅读更多关于如何使用此事件的信息。

`astro:after-preparation` 事件

在使用视图转换路由器进行导航时，加载下一页后派发的事件。

此事件没有属性。

在视图转换指南中阅读更多关于如何使用此事件的信息。

`astro:before-swap` 事件

在下一页被解析、准备并链接到文档中以准备过渡之后，但在文档之间交换任何内容之前派发的事件。

此事件无法取消。调用 preventDefault() 是一个空操作。

此事件具有以下属性

info
sourceElement
navigationType
direction
from
to
viewTransition
swap()

在视图转换指南中阅读更多关于如何使用此事件的信息。

`astro:after-swap` 事件

在页面内容被交换之后，但在视图转换结束之前派发的事件。

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

`astro:page-load` 事件

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

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

生命周期事件属性

添加于： astro@3.6.0

`info`

类型： any

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

这是传递给 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`

类型： any

发起导航的页面的 URL。

`to`

类型： any

要导航到的页面的 URL。此属性可以被修改，生命周期结束时的值将用于下一页的 NavigationHistoryEntry。

`formData`

类型： FormData | undefined

用于 POST 请求的 FormData 对象。

设置此属性后，将向 to URL 发送一个 POST 请求，并将给定的表单数据对象作为内容，而不是常规的 GET 请求。

在启用视图转换的情况下提交 HTML 表单时，此字段会自动设置为表单中的数据。当使用 navigate() 函数时，此值与选项中给定的值相同。

`loader()`

类型： () => Promise<void>

导航中下一阶段（加载下一页）的实现。可以重写此实现以添加额外的行为。

`viewTransition`

类型： ViewTransition

此导航中使用的视图转换对象。在不支持视图转换 API的浏览器上，这是一个为方便起见实现相同 API 但没有 DOM 集成的对象。

`swap()`

类型： () => void

文档交换逻辑的实现。

在视图转换指南中阅读更多关于构建自定义交换函数的信息。

默认情况下，此实现将按顺序调用以下函数

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

贡献社区赞助

视图转换路由器 API 参考

从 astro:transitions 导入

<ClientRouter />

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

`<ClientRouter />`

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