视图过渡动画 API 参考
添加于:
astro@3.0.0
此模块提供了一些函数,用于控制和与视图过渡 API 和客户端路由进行交互。
对于功能和使用示例,请参阅我们的视图过渡指南。
从 astro:transitions
导入
段落标题 从 astro:transitions 导入<ViewTransitions />
段落标题 <ViewTransitions />
添加于:
astro@3.0.0
通过将 <ViewTransitions />
路由组件导入并添加到每个所需页面的 <head>
部分,以选择在各个页面上使用视图过渡动画。
查看有关如何 控制路由器以及 添加过渡指令 到页面元素和组件的更多信息。
fade
段落标题 fade类型: (opts: { duration?: string | number }) => TransitionDirectionalAnimations
astro@3.0.0
支持自定义内置 fade
动画持续时间的实用函数。
slide
段落标题 slide类型: (opts: { duration?: string | number }) => TransitionDirectionalAnimations
astro@3.0.0
支持自定义内置 slide
动画持续时间的实用函数。
从 astro:transitions/client
导入
段落标题 从 astro:transitions/client 导入navigate()
段落标题 navigate()类型:(href: string, options?: Options) => void
astro@3.2.0
一个使用视图过渡 API 导航到给定 href
的函数。
此函数签名基于 浏览器 Navigation API 中的 navigate
函数。虽然基于 Navigation API,但此函数是在 History API 之上实现的,以允许在不重新加载页面的情况下进行导航。
history
选项
段落标题 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 选项类型:FormData
astro@3.5.0
一个 FormData
对象,用于 POST
请求。
当提供此选项时,导航目标页面的请求将以 POST
请求的形式发送,内容为表单数据对象。
当提交一个带有视图过渡的 HTML 表单时,将使用此方法代替默认的页面重新加载导航。调用此方法允许以编程方式触发相同的行为。
info
选项
段落标题 info 选项类型:any
astro@3.6.0
与导航相关的 astro:before-preparation
和 astro:before-swap
事件中包含的任意数据。
此选项模仿了浏览器 Navigation API 中的 info
选项。
state
选项
段落标题 state 选项类型:any
astro@3.6.0
与导航相关的 NavitationHistoryEntry
对象中关联的任意数据。此数据可以通过 history.getState
函数 从 History API 中检索。
此选项模仿了浏览器 Navigation API 中的 state
选项。
sourceElement
选项
段落标题 sourceElement 选项类型:Element
astro@3.6.0
此导航的触发元素,如果有的话。此元素将在以下事件中可用:
astro:before-preparation
astro:before-swap
supportsViewTransitions
段落标题 supportsViewTransitions类型:boolean
astro@3.2.0
当前浏览器是否支持并启用视图过渡。
transitionEnabledOnThisPage
段落标题 transitionEnabledOnThisPage类型:boolean
astro@3.2.0
当前页面是否启用了视图过渡以进行客户端导航。这可以用于使组件在视图过渡页面上的行为有所不同。
getFallback
段落标题 getFallback类型:() => 'none' | 'animate' | 'swap'
astro@3.6.0
返回在浏览器不支持视图过渡时使用的回退策略。
有关如何选择和配置回退行为的详细信息,请参阅 回退控制 指南。
swapFunctions
段落标题 swapFunctions
添加于:
astro@4.15.0
一个对象,其中包含了用于构建 Astro 默认交换函数的工具类函数。 这些函数在 构建自定义交换函数 时非常有用。
swapFunctions
提供了以下方法:
deselectScripts()
段落标题 deselectScripts()类型: (newDocument: Document) => void
标记在新的 document 中不应执行的脚本。这些脚本已经在当前 document 中,并且没有使用 data-astro-rerun
标记为重新执行。
swapRootAttributes()
段落标题 swapRootAttributes()类型:(newDocument: Document) => void
在 document 根节点之间交换属性,如 lang
属性。这也包括 Astro 注入的内部属性,如 data-astro-transition
,这使得过渡方向可用于 Astro 生成的 CSS 规则。
在构建自定义交换函数时,重要的是调用此函数,以避免破坏视图过渡的动画。
swapHeadElements()
段落标题 swapHeadElements()类型:(newDocument: Document) => void
从当前 document 的 <head>
中删除所有未持久化到新 document 的元素。然后将新 document 的 <head>
中的所有新元素附加到当前 document 的 <head>
。
saveFocus()
段落标题 saveFocus()类型:() => () => void
在当前页面上存储聚焦的元素,并返回一个函数,当调用时,如果聚焦的元素被持久化,则将焦点返回给该元素。
swapBodyElement()
段落标题 swapBodyElement()类型:(newBody: Element, oldBody: Element) => void
用新 document 的 body 替换旧的 body。然后,遍历旧 body 中应持久化的每个元素,并在新 body 中找到匹配的元素,将旧元素交换回原位。
生命周期事件
段落标题 生命周期事件astro:before-preparation
事件
段落标题 astro:before-preparation 事件在视图过渡中导航开始时触发的事件。此事件发生在任何请求之前,并且不会更改任何浏览器状态。
此事件具有以下属性:
有关如何使用此事件的详细信息,请参阅 视图过渡指南。
astro:after-preparation
事件
段落标题 astro:after-preparation 事件使用视图过渡加载导航中的下一个页面后触发的事件。
此事件没有属性。
有关如何使用此事件的详细信息,请参阅 视图过渡指南。
astro:before-swap
事件
段落标题 astro:before-swap 事件在视图过渡中导航的下一个页面解析、准备并链接到 document 后,但在任何内容在 document 之间交换之前触发的事件。
此事件不能取消。调用 preventDefault()
是无效的。
此事件具有以下属性:
有关如何使用此事件的详细信息,请参阅 视图过渡指南。
astro:after-swap
事件
段落标题 astro:after-swap 事件在视图过渡中导航的下一个页面内容交换后,但在视图过渡结束之前触发的事件。
在触发此事件时,历史记录条目和滚动位置已经更新。
astro:page-load
事件
段落标题 astro:page-load 事件在页面完成加载后触发的事件,无论是通过视图过渡导航还是浏览器原生导航。
当视图过渡在页面上启用时,通常在 DOMContentLoaded
上执行的代码应更改为在此事件上执行。
生命周期事件属性
段落标题 生命周期事件属性
添加于:
astro@3.6.0
info
段落标题 info类型:URL
在导航期间定义的任意数据。
这是在 navigate()
函数 的 info
选项 中传递的文字值。
sourceElement
段落标题 sourceElement类型:Element | undefined
触发导航的元素。例如,这可以是点击的 <a>
元素。
当使用 navigate()
函数 时,这将是调用中指定的元素。
newDocument
段落标题 newDocument类型:Document
导航中下一个页面的 document。此 document 的内容将替换当前 document 的内容。
navigationType
段落标题 navigationType类型:'push' | 'replace' | 'traverse'
正在发生的导航类型。
push
: 正在为新页面创建一个新的NavigationHistoryEntry
。replace
: 当前的NavigationHistoryEntry
正在被新页面的条目替换。traverse
: 没有创建NavigationHistoryEntry
。历史记录中的位置正在改变。 遍历的方向由direction
属性 给出
direction
段落标题 direction类型:Direction
过渡的方向。
forward
: 在历史记录中导航到下一个页面或新页面。back
: 在历史记录中导航到前一个页面。- 其他监听器可能设置的任何其他内容。
from
段落标题 from类型:URL
正在导航的页面的 URL。
to
段落标题 to类型:URL
正在导航的页面的 URL。此属性可以修改,在生命周期结束时使用的值将是下一个页面的 NavigationHistoryEntry
的值。
formData
段落标题 formData类型:FormData | undefined
一个用于 POST
请求的 FormData
对象。
当此属性设置时,将使用给定的表单数据对象作为内容发送 POST
请求到 to
URL,而不是正常的 GET
请求。
当提交一个带有视图过渡的 HTML 表单时,此字段会自动设置为表单中的数据。当使用 navigate()
函数 时,此值与给定的选项相同。
loader
段落标题 loader类型:() => Promise<void>
在导航过程中下个阶段的实现(加载下一个页面)。此实现可以覆盖以添加额外的行为。
viewTransition
段落标题 viewTransition在导航过程中使用的视图过渡对象。在浏览器不支持 视图过渡 API 的情况下,这是一个对象,实现了相同的 API 以方便使用,但没有 DOM 集成。
swap
段落标题 swap类型:() => void
document 交换逻辑的实现。
有关如何构建自定义交换函数的详细信息,请参阅 视图过渡指南.
默认情况下,此实现将按顺序调用以下函数:
Reference