查看转换路由 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 导入
Section titled “从 astro:transitions 导入”¥Imports from astro:transitions
import { ClientRouter, fade, slide,} from 'astro:transitions';<ClientRouter />
Section titled “<ClientRouter />”
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.
---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
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
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 导入
Section titled “从 astro:transitions/client 导入”¥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';navigate()
Section titled “navigate()”类型:(href: string, options?: Options) => void
¥Type: (href: string, options?: Options) => void
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 选项
Section titled “history 选项”¥history option
类型:'auto' | 'push' | 'replace'
默认:'auto'
¥Type: 'auto' | 'push' | 'replace'
Default: 'auto'
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 选项
Section titled “formData 选项”¥formData option
类型:FormData
¥Type: FormData
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 选项
Section titled “info 选项”¥info option
类型:any
¥Type: any
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 选项
Section titled “state 选项”¥state option
类型:any
¥Type: any
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 选项
Section titled “sourceElement 选项”¥sourceElement option
类型:Element
¥Type: Element
astro@3.6.0
触发此导航的元素(如果有)。此元素将在以下事件中可用:
¥The element that triggered this navigation, if any. This element will be available in the following events:
supportsViewTransitions
Section titled “supportsViewTransitions”类型:boolean
¥Type: boolean
astro@3.2.0
当前浏览器是否支持并启用视图转换。
¥Whether or not view transitions are supported and enabled in the current browser.
transitionEnabledOnThisPage()
Section titled “transitionEnabledOnThisPage()”类型:() => boolean
¥Type: () => boolean
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()
Section titled “getFallback()”类型:() => Fallback
默认:animate
¥Type: () => Fallback
Default: animate
astro@3.6.0
返回在不支持视图过渡的浏览器中要使用的回退策略(默认为 animate)。
¥Returns the fallback strategy to use (animate by default) in browsers that do not support view transitions.
swapFunctions
Section titled “swapFunctions”类型:object
¥Type: object
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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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()
Section titled “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.
已弃用的导入
Section titled “已弃用的导入”¥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
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.
------
<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
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.
------
<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'
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.
------
<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'
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.
------
<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'
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.
------
<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'
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.
------
<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'
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.
------
<script> import { TRANSITION_PAGE_LOAD } from "astro:transitions/client";
document.addEventListener(TRANSITION_PAGE_LOAD, () => { /* the listener logic */ });</script>astro:transitions/client 类型
Section titled “astro:transitions/client 类型”¥astro:transitions/client types
import type { Direction, Fallback, NavigationTypeString, Options, TransitionBeforePreparationEvent, TransitionBeforeSwapEvent,} from 'astro:transitions/client';Direction
Section titled “Direction”类型:'forward' | 'back'
¥Type: 'forward' | 'back'
astro@3.2.0
动画方向的并集:
¥A union of animation directions:
-
forward:导航到历史记录中的下一页或新页面。 -
back:导航到历史记录中的上一页。
Fallback
Section titled “Fallback”类型:'none' | 'animate' | 'swap'
¥Type: 'none' | 'animate' | 'swap'
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 根本不会做任何动画页面转换。相反,你将在不支持的浏览器中获得完整页面导航。
ClientRouter.
NavigationTypeString
Section titled “NavigationTypeString”类型:'push' | 'replace' | 'traverse'
¥Type: 'push' | 'replace' | 'traverse'
astro@3.6.0
受支持的历史导航事件的并集。
¥A union of supported history navigation events.
TransitionBeforePreparationEvent
Section titled “TransitionBeforePreparationEvent”类型:Event
¥Type: Event
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:
------
<script> import { TRANSITION_BEFORE_PREPARATION, type TransitionBeforePreparationEvent } from "astro:transitions/client";
function listener(event: TransitionBeforePreparationEvent) { /* do something */ }
document.addEventListener(TRANSITION_BEFORE_PREPARATION, listener);</script>TransitionBeforeSwapEvent
Section titled “TransitionBeforeSwapEvent”类型:Event
¥Type: Event
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:
------
<script> import { TRANSITION_BEFORE_SWAP, type TransitionBeforeSwapEvent } from "astro:transitions/client";
function listener(event: TransitionBeforeSwapEvent) { /* do something */ }
document.addEventListener(TRANSITION_BEFORE_SWAP, listener);</script>生命周期事件
Section titled “生命周期事件”¥Lifecycle events
astro:before-preparation 事件
Section titled “astro:before-preparation 事件”¥astro:before-preparation event
类型:TransitionBeforePreparationEvent
¥Type: TransitionBeforePreparationEvent
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:
astro:after-preparation 事件
Section titled “astro:after-preparation 事件”¥astro:after-preparation event
类型:Event
¥Type: Event
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.
astro:before-swap 事件
Section titled “astro:before-swap 事件”¥astro:before-swap event
¥Type: TransitionBeforeSwapEvent
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:
astro:after-swap 事件
Section titled “astro:after-swap 事件”¥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 事件
Section titled “astro:page-load 事件”¥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.
生命周期事件属性
Section titled “生命周期事件属性”¥Lifecycle events attributes
Added in:
astro@3.6.0
以下属性是 astro:before-preparation 和 astro: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.
sourceElement
Section titled “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
Section titled “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
Section titled “navigationType”¥Type: NavigationTypeString
正在发生哪种历史导航。
¥Which kind of history navigation is happening.
-
push:正在为新页面创建新的NavigationHistoryEntry。 -
replace:当前NavigationHistoryEntry将被新页面的条目替换。 -
traverse:未创建NavigationHistoryEntry。历史记录中的位置正在发生变化。direction属性 中指定了遍历方向。
direction
Section titled “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
Section titled “formData”类型: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.
loader()
Section titled “loader()”类型:() => 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
Section titled “viewTransition”类型: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.
swap()
Section titled “swap()”类型:() => 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: