查看转换路由 API 参考

Added in: astro@3.0.0

这些模块提供控制和与 View Transitions API 和客户端路由交互的功能。

¥These modules provide functions to control and interact with the View Transitions API and client-side router.

¥For features and usage examples, see our View Transitions guide.

从 `astro:transitions` 导入

¥Imports from astro:transitions

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

`<ClientRouter />`

Added in: astro@3.0.0

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

¥Opt in to using view transitions on individual pages by importing and adding the <ClientRouter /> routing component to <head> on every desired page.

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

详细了解如何通过控制路由和添加转换指令来页面元素和组件。

¥See more about how to control the router and add transition directives to page elements and components.

`fade`

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

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

Added in: astro@3.0.0

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

¥Utility function to support customizing the duration of the built-in fade animation.

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

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

Added in: astro@3.0.0

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

¥Utility function to support customizing the duration of the built-in slide animation.

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

¥Imports from astro:transitions/client

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

`navigate()`

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

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

Added in: astro@3.2.0

使用 View Transitions API 执行到给定 href 的导航的函数。

¥A function that executes a navigation to the given href using the View Transitions API.

此函数签名基于来自浏览器导航 API 的 navigate 函数。尽管基于导航 API，但此功能是在历史 API 之上实现的，以允许导航而无需重新加载页面。

¥This function signature is based on the navigate function from the browser Navigation API. Although based on the Navigation API, this function is implemented on top of the History API to allow for navigation without reloading the page.

`history` 选项

¥history option

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

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

Added in: astro@3.2.0

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

¥Defines how this navigation should be added to the browser history.

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

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

¥This option follows the history option from the browser Navigation API but simplified for the cases that can happen on an Astro project.

`formData` 选项

¥formData option

类型：FormData

¥Type: FormData

Added in: astro@3.5.0

POST 请求的 FormData 对象。

¥A FormData object for POST requests.

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

¥When this option is provided, the requests to the navigation target page will be sent as a POST request with the form data object as the content.

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

¥Submitting an HTML form with view transitions enabled will use this method instead of the default navigation with page reload. Calling this method allows triggering the same behavior programmatically.

`info` 选项

¥info option

类型：any

¥Type: any

Added in: astro@3.6.0

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

¥Arbitrary data to be included in the astro:before-preparation and astro:before-swap events caused by this navigation.

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

¥This option mimics the info option from the browser Navigation API.

`state` 选项

¥state option

类型：any

¥Type: any

Added in: astro@3.6.0

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

¥Arbitrary data to be associated with the NavitationHistoryEntry object created by this navigation. This data can then be retrieved using the history.getState function from the History API.

此选项模仿浏览器导航 API 中的 state 选项。

¥This option mimics the state option from the browser Navigation API.

`sourceElement` 选项

¥sourceElement option

类型：Element

¥Type: Element

Added in: astro@3.6.0

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

¥The element that triggered this navigation, if any. This element will be available in the following events:

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

类型：boolean

¥Type: boolean

Added in: astro@3.2.0

当前浏览器是否支持并启用视图转换。

¥Whether or not view transitions are supported and enabled in the current browser.

`transitionEnabledOnThisPage`

类型：boolean

¥Type: boolean

Added in: astro@3.2.0

当前页面是否为客户端导航启用了视图转换。这可用于制作在具有视图转换的页面上使用时行为不同的组件。

¥Whether or not the current page has view transitions enabled for client-side navigation. This can be used to make components that behave differently when they are used on pages with view transitions.

`getFallback()`

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

¥Type: () => 'none' | 'animate' | 'swap'

Added in: astro@3.6.0

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

¥Returns the fallback strategy to use in browsers that do not support view transitions.

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

¥See the guide on Fallback control for how to choose and configure the fallback behavior.

`swapFunctions`

Added in: astro@4.15.0

包含用于构建 Astro 默认交换函数的实用函数的对象。当构建自定义交换函数时，这些会很有用。

¥An object containing the utility functions used to build Astro’s default swap function. These can be useful when building a custom swap function.

swapFunctions 提供以下方法：

¥swapFunctions provides the following methods:

`deselectScripts()`

类型：(newDocument: Document) => void

¥Type: (newDocument: Document) => void

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

¥Marks scripts in the new document that should not be executed. Those scripts are already in the current document and are not flagged for re-execution using data-astro-rerun.

`swapRootAttributes()`

类型：(newDocument: Document) => void

¥Type: (newDocument: Document) => void

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

¥Swaps the attributes between the document roots, like the lang attribute. This also includes Astro-injected internal attributes like data-astro-transition, which makes the transition direction available to Astro-generated CSS rules.

制作自定义交换函数时，调用此函数很重要，以免破坏视图转换的动画。

¥When making a custom swap function, it is important to call this function so as not to break the view transition’s animations.

`swapHeadElements()`

类型：(newDocument: Document) => void

¥Type: (newDocument: Document) => void

从当前文档的 <head> 中删除未保留到新文档的每个元素。然后将新文档的 <head> 中的所有新元素附加到当前文档的 <head>。

¥Removes every element from the current document’s <head> that is not persisted to the new document. Then appends all new elements from the new document’s <head> to the current document’s <head>.

`saveFocus()`

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

¥Type: () => () => void

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

¥Stores the element in focus on the current page and returns a function that when called, if the focused element was persisted, returns the focus to it.

`swapBodyElement()`

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

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

用新主体替换旧主体。然后，遍历旧主体中应保留的每个元素，并在新主体中具有匹配的元素，然后将旧元素交换回原位。

¥Replaces the old body with the new body. Then, goes through every element in the old body that should be persisted and have a matching element in the new body and swaps the old element back in place.

生命周期事件

¥Lifecycle events

`astro:before-preparation` 事件

¥astro:before-preparation event

在使用 View Transitions 路由的导航开始时调度的事件。此事件发生在发出任何请求和更改任何浏览器状态之前。

¥An event dispatched at the beginning of a navigation using the View Transitions router. This event happens before any request is made and any browser state is changed.

此事件具有以下属性：

¥This event has the attributes:

info
sourceElement
navigationType
direction
from
to
formData
loader()

阅读有关如何在查看转换指南上使用此事件的更多信息。

¥Read more about how to use this event on the View Transitions guide.

`astro:after-preparation` 事件

¥astro:after-preparation event

在使用 View Transitions 路由的导航中加载下一页后调度的事件。

¥An event dispatched after the next page in a navigation using View Transitions router is loaded.

此事件没有属性。

¥This event has no attributes.

阅读有关如何在查看转换指南上使用此事件的更多信息。

¥Read more about how to use this event on the View Transitions guide.

`astro:before-swap` 事件

¥astro:before-swap event

在解析、准备下一页并将其链接到文档以准备转换但在文档之间交换任何内容之前分派的事件。

¥An event dispatched after the next page is parsed, prepared, and linked into a document in preparation for the transition but before any content is swapped between the documents.

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

¥This event can’t be canceled. Calling preventDefault() is a no-op.

此事件具有以下属性：

¥This event has the attributes:

info
sourceElement
navigationType
direction
from
to
viewTransition
swap()

阅读有关如何在查看转换指南上使用此事件的更多信息。

¥Read more about how to use this event on the View Transitions guide.

`astro:after-swap` 事件

¥astro:after-swap event

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

¥An event dispatched after the contents of the page have been swapped but before the view transition ends.

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

¥The history entry and scroll position have already been updated when this event is triggered.

`astro:page-load` 事件

¥astro:page-load event

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

¥An event dispatched after a page completes loading, whether from a navigation using view transitions or native to the browser.

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

¥When view transitions is enabled on the page, code that would normally execute on DOMContentLoaded should be changed to execute on this event.

生命周期事件属性

¥Lifecycle events attributes

Added in: astro@3.6.0

`info`

类型：URL

¥Type: URL

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

¥Arbitrary data defined during navigation.

这是在 navigate() 功能的 info 选项上传递的字面量值。

¥This is the literal value passed on the info option of the navigate() function.

`sourceElement`

类型：Element | undefined

¥Type: Element | undefined

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

¥The element that triggered the navigation. This can be, for example, an <a> element that was clicked.

使用 navigate() 功能时，这将是调用中指定的元素。

¥When using the navigate() function, this will be the element specified in the call.

`newDocument`

类型：Document

¥Type: Document

导航中下一页的文档。此文档的内容将替换当前文档的内容。

¥The document for the next page in the navigation. The contents of this document will be swapped in place of the contents of the current document.

`navigationType`

类型：'push' | 'replace' | 'traverse'

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

正在发生哪种历史导航。

¥Which kind of history navigation is happening.

push：正在为新页面创建新的 NavigationHistoryEntry。
replace：当前 NavigationHistoryEntry 将被新页面的条目替换。
traverse：未创建 NavigationHistoryEntry。历史记录中的位置正在发生变化。遍历的方向在 direction 属性上给出

`direction`

类型：Direction

¥Type: Direction

转换的方向。

¥The direction of the transition.

forward：导航到历史记录中的下一页或新页面。
back：导航到历史记录中的上一页。
其他监听器可能设置的任何其他内容。

`from`

类型：URL

¥Type: URL

启动导航的页面的 URL。

¥The URL of the page initiating the navigation.

`to`

类型：URL

¥Type: URL

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

¥The URL of the page being navigated to. This property can be modified, the value at the end of the lifecycle will be used in the NavigationHistoryEntry for the next page.

`formData`

类型：FormData | undefined

¥Type: FormData | undefined

POST 请求的 FormData 对象。

¥A FormData object for POST requests.

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

¥When this attribute is set, a POST request will be sent to the to URL with the given form data object as the content instead of the normal GET request.

提交启用了视图转换的 HTML 表单时，此字段会自动设置为表单中的数据。使用 navigate() 功能时，此值与选项中给出的值相同。

¥When submitting an HTML form with view transitions enabled, this field is automatically set to the data in the form. When using the navigate() function, this value is the same as given in the options.

`loader()`

类型：() => Promise<void>

¥Type: () => Promise<void>

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

¥Implementation of the following phase in the navigation (loading the next page). This implementation can be overridden to add extra behavior.

`viewTransition`

类型：ViewTransition

¥Type: ViewTransition

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

¥The view transition object used in this navigation. On browsers that do not support the View Transitions API, this is an object implementing the same API for convenience but without the DOM integration.

`swap()`

类型：() => void

¥Type: () => void

文档交换逻辑的实现。

¥Implementation of the document swap logic.

在“查看转换”指南中阅读有关构建自定义交换函数的更多信息。

¥Read more about building a custom swap function in the View Transitions guide.

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

¥By default, this implementation will call the following functions in order:

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