Skip to content

查看转换路由 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.

¥Imports from astro:transitions

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

Added in: astro@5.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.

src/pages/index.astro
---
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.

<ClientRouter /> 组件接受以下属性:

¥The <ClientRouter /> component accepts the following props:

fallback

类型:Fallback
默认:animate

¥Type: Fallback
Default: animate

定义不支持 视图转换 API 的浏览器的回退策略。

¥Defines the fallback strategy to use for browsers that do not support the View Transitions API.

类型:(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' })} />

类型:(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' })} />

¥Imports from astro:transitions/client

import {
getFallback,
navigate,
supportsViewTransitions,
swapFunctions,
transitionEnabledOnThisPage,
/* The following are scheduled for deprecation in v6: */
isTransitionBeforePreparationEvent,
isTransitionBeforeSwapEvent,
TRANSITION_AFTER_PREPARATION,
TRANSITION_AFTER_SWAP,
TRANSITION_BEFORE_PREPARATION,
TRANSITION_BEFORE_SWAP,
TRANSITION_PAGE_LOAD,
} from 'astro:transitions/client';

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

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

Added in: astro@3.2.0

使用视图转换 API 执行到指定 href 的导航。

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

navigate() 不会对 href 参数执行清理。如果你使用 用户输入清理 来确定要导航到的 URL,则可以使用它。

¥navigate() does not perform sanitization on the href parameter. Sanitize user input if you use it to determine the URL to navigate to.

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

类型:any

¥Type: any

Added in: astro@3.6.0

此导航引起的 astro:before-preparationastro: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 option

类型:any

¥Type: any

Added in: astro@3.6.0

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

¥Arbitrary data to be associated with the NavigationHistoryEntry 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 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:

类型:boolean

¥Type: boolean

Added in: astro@3.2.0

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

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

类型:() => 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.

类型:() => Fallback
默认:animate

¥Type: () => Fallback
Default: animate

Added in: astro@3.6.0

返回在不支持视图过渡的浏览器中要使用的回退策略(默认为 animate)。

¥Returns the fallback strategy to use (animate by default) in browsers that do not support view transitions.

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

类型:object

¥Type: object

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:

类型:(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.

类型:(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.

类型:(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>.

类型:() => () => 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.

类型:(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.

¥Deprecated imports

以下导入项计划在 v6 版本中弃用。你仍然可以在项目中使用它们,但你可能更倾向于现在更新代码。

¥The following imports are scheduled for deprecation in v6. You can still use them in your project, but you may prefer to update your code now.

isTransitionBeforePreparationEvent()

类型:(value: any) => boolean

¥Type: (value: any) => boolean

Added in: astro@3.6.0

确定给定值是否与 TransitionBeforePreparationEvent 匹配。当你需要在事件监听器中缩小事件类型范围时,这将非常有用。

¥Determines whether the given value matches a TransitionBeforePreparationEvent. This can be useful when you need to narrow the type of an event in an event listener.

src/pages/index.astro
---
---
<script>
import {
isTransitionBeforePreparationEvent,
TRANSITION_BEFORE_PREPARATION,
} from "astro:transitions/client";
function listener(event: Event) {
const setting = isTransitionBeforePreparationEvent(event) ? 1 : 2;
/* do something with setting */
}
document.addEventListener(TRANSITION_BEFORE_PREPARATION, listener);
</script>

isTransitionBeforeSwapEvent()

类型:(value: any) => boolean

¥Type: (value: any) => boolean

Added in: astro@3.6.0

确定给定值是否与 TransitionBeforeSwapEvent 匹配。当你需要在事件监听器中缩小事件类型范围时,这将非常有用。

¥Determines whether the given value matches a TransitionBeforeSwapEvent. This can be useful when you need to narrow the type of an event in an event listener.

src/pages/index.astro
---
---
<script>
import {
isTransitionBeforeSwapEvent,
TRANSITION_BEFORE_SWAP,
} from "astro:transitions/client";
function listener(event: Event) {
const setting = isTransitionBeforeSwapEvent(event) ? 1 : 2;
/* do something with setting */
}
document.addEventListener(TRANSITION_BEFORE_SWAP, listener);
</script>

TRANSITION_BEFORE_PREPARATION

类型:'astro:before-preparation'

¥Type: 'astro:before-preparation'

Added in: astro@3.6.0

一个常量,用于在定义事件时避免以纯文本形式写入 astro:before-preparation 事件名称。

¥A constant to avoid writing the astro:before-preparation event name in plain text when you define an event.

src/pages/index.astro
---
---
<script>
import { TRANSITION_BEFORE_PREPARATION } from "astro:transitions/client";
document.addEventListener(TRANSITION_BEFORE_PREPARATION, () => {
/* the listener logic */
});
</script>

TRANSITION_AFTER_PREPARATION

类型:'astro:after-preparation'

¥Type: 'astro:after-preparation'

Added in: astro@3.6.0

一个常量,用于在定义事件时避免以纯文本形式写入 astro:after-preparation 事件名称。

¥A constant to avoid writing the astro:after-preparation event name in plain text when you define an event.

src/pages/index.astro
---
---
<script>
import { TRANSITION_AFTER_PREPARATION } from "astro:transitions/client";
document.addEventListener(TRANSITION_AFTER_PREPARATION, () => {
/* the listener logic */
});
</script>

TRANSITION_BEFORE_SWAP

类型:'astro:before-swap'

¥Type: 'astro:before-swap'

Added in: astro@3.6.0

一个常量,用于在定义事件时避免以纯文本形式写入 astro:before-swap 事件名称。

¥A constant to avoid writing the astro:before-swap event name in plain text when you define an event.

src/pages/index.astro
---
---
<script>
import { TRANSITION_BEFORE_SWAP } from "astro:transitions/client";
document.addEventListener(TRANSITION_BEFORE_SWAP, () => {
/* the listener logic */
});
</script>

TRANSITION_AFTER_SWAP

类型:'astro:after-swap'

¥Type: 'astro:after-swap'

Added in: astro@3.6.0

一个常量,用于在定义事件时避免以纯文本形式写入 astro:after-swap 事件名称。

¥A constant to avoid writing the astro:after-swap event name in plain text when you define an event.

src/pages/index.astro
---
---
<script>
import { TRANSITION_AFTER_SWAP } from "astro:transitions/client";
document.addEventListener(TRANSITION_AFTER_SWAP, () => {
/* the listener logic */
});
</script>

TRANSITION_PAGE_LOAD

类型:'astro:page-load'

¥Type: 'astro:page-load'

Added in: astro@3.6.0

一个常量,用于在定义事件时避免以纯文本形式写入 astro:page-load 事件名称。

¥A constant to avoid writing the astro:page-load event name in plain text when you define an event.

src/pages/index.astro
---
---
<script>
import { TRANSITION_PAGE_LOAD } from "astro:transitions/client";
document.addEventListener(TRANSITION_PAGE_LOAD, () => {
/* the listener logic */
});
</script>

¥astro:transitions/client types

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

类型:'forward' | 'back'

¥Type: 'forward' | 'back'

Added in: astro@3.2.0

动画方向的并集:

¥A union of animation directions:

  • forward:导航到历史记录中的下一页或新页面。

  • back:导航到历史记录中的上一页。

类型:'none' | 'animate' | 'swap'

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

Added in: astro@3.2.0

在不支持视图过渡的浏览器中使用的回退策略的并集:

¥A union of fallback strategies to use in browsers that do not support view transitions:

  • animate:Astro 会在更新页面内容之前使用自定义属性模拟视图转换。

  • swap:Astro 不会尝试为页面添加动画效果。相反,旧页面将立即被新页面替换。

  • none:Astro 根本不会做任何动画页面转换。相反,你将在不支持的浏览器中获得完整页面导航。

Learn more about controlling the fallback strategy with the ClientRouter.

类型:'push' | 'replace' | 'traverse'

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

Added in: astro@3.6.0

受支持的历史导航事件的并集。

¥A union of supported history navigation events.

类型:Event

¥Type: Event

Added in: astro@3.6.0

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

¥Represents an astro:before-preparation event. This can be useful to type the event received by a listener:

src/pages/index.astro
---
---
<script>
import {
TRANSITION_BEFORE_PREPARATION,
type TransitionBeforePreparationEvent
} from "astro:transitions/client";
function listener(event: TransitionBeforePreparationEvent) {
/* do something */
}
document.addEventListener(TRANSITION_BEFORE_PREPARATION, listener);
</script>

类型:Event

¥Type: Event

Added in: astro@3.6.0

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

¥Represents an astro:before-swap event. This can be useful to type the event received by a listener:

src/pages/index.astro
---
---
<script>
import {
TRANSITION_BEFORE_SWAP,
type TransitionBeforeSwapEvent
} from "astro:transitions/client";
function listener(event: TransitionBeforeSwapEvent) {
/* do something */
}
document.addEventListener(TRANSITION_BEFORE_SWAP, listener);
</script>

¥Lifecycle events

¥astro:before-preparation event

类型:TransitionBeforePreparationEvent

¥Type: TransitionBeforePreparationEvent

Added in: astro@3.6.0

在使用 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:

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

¥astro:after-preparation event

类型:Event

¥Type: Event

Added in: astro@3.6.0

在使用 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 event

类型:TransitionBeforeSwapEvent

¥Type: TransitionBeforeSwapEvent

Added in: astro@3.6.0

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

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

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

¥astro:after-swap event

类型:Event

¥Type: 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 event

类型:Event

¥Type: 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

以下属性是 astro:before-preparationastro:before-swap 事件共有的,但有些属性仅适用于其中一个事件。

¥The following attributes are common to both the astro:before-preparation and astro:before-swap events, except for some that are only available with one or the other.

类型:any

¥Type: any

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

¥Arbitrary data defined during navigation.

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

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

类型: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.

类型: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.

类型:NavigationTypeString

¥Type: NavigationTypeString

正在发生哪种历史导航。

¥Which kind of history navigation is happening.

  • push:正在为新页面创建新的 NavigationHistoryEntry

  • replace:当前 NavigationHistoryEntry 将被新页面的条目替换。

  • traverse:未创建 NavigationHistoryEntry。历史记录中的位置正在发生变化。direction 属性 中指定了遍历方向。

类型:string

¥Type: string

过渡方向:

¥The direction of the transition:

  • astro:before-preparation 事件 中,可以使用此关键字定义自定义方向。该属性为可写属性,可接受任何字符串。

  • astro:before-swap 事件 中,可以使用此关键字检索过渡方向。该属性为只读属性,其值可以是预定义的 Direction 值,也可以是 astro:before-preparation 事件监听器可能设置的任何字符串。

类型:URL

¥Type: URL

启动导航的页面的 URL。

¥The URL of the page initiating the navigation.

类型: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 | undefined
可用:astro:before-preparation 事件

¥Type: FormData | undefined
Available in: astro:before-preparation event

设置后,系统会向 to URL 发送一个 POST 请求,并将给定的 FormData 对象作为内容,而不是发送普通的 GET 请求。

¥When set, a POST request will be sent to the to URL with the given FormData 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.

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

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

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

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

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

¥Type: ViewTransition
Available in: astro:before-swap event

此导航中使用的视图转换对象。在不支持 视图转换 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.

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

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

调用默认的文档交换逻辑。默认情况下,此实现将按顺序调用以下函数:

¥Calls the default document swap logic. By default, this implementation will call the following functions in order:

  1. deselectScripts()
  2. swapRootAttributes()
  3. swapHeadElements()
  4. saveFocus()
  5. swapBodyElement()
Read more about building a custom swap function in the View Transitions guide.
Astro v5.16 中文网 - 粤ICP备13048890号