过渡
<Transition> 组件在页面和布局之间应用过渡效果。页面过渡
您可以启用页面过渡，以便对所有 页面 应用自动过渡。
export default defineNuxtConfig({
app: {
pageTransition: { name: 'page', mode: 'out-in' }
},
})
要开始在您的页面之间添加过渡，请将以下 CSS 添加到您的 app.vue:
<template>
<NuxtPage />
</template>
<style>
.page-enter-active,
.page-leave-active {
transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
opacity: 0;
filter: blur(1rem);
}
</style>
在页面之间导航时将产生以下效果：
要为页面设置不同的过渡，请在页面的 definePageMeta 中设置 pageTransition 键：
<script setup lang="ts">
definePageMeta({
pageTransition: {
name: 'rotate'
}
})
</script>
移动到关于页面将添加 3D 旋转效果：
布局过渡
您可以启用布局过渡，以便对所有 布局 应用自动过渡。
export default defineNuxtConfig({
app: {
layoutTransition: { name: 'layout', mode: 'out-in' }
},
})
要开始在页面和布局之间添加过渡，请将以下 CSS 添加到您的 app.vue:
<template>
<NuxtLayout>
<NuxtPage />
</NuxtLayout>
</template>
<style>
.layout-enter-active,
.layout-leave-active {
transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
filter: grayscale(1);
}
</style>
在页面之间导航时将产生以下效果：
类似于 pageTransition，您可以使用 definePageMeta 将自定义 layoutTransition 应用到页面组件：
<script setup lang="ts">
definePageMeta({
layout: 'orange',
layoutTransition: {
name: 'slide-in'
}
})
</script>
全局设置
您可以通过 nuxt.config 在全局范围内自定义这些默认过渡名称。
pageTransition 和 layoutTransition 键接受 TransitionProps 作为 JSON 可序列化值，您可以在其中传递 name、mode 和其他有效的过渡属性来定义自定义 CSS 过渡。
export default defineNuxtConfig({
app: {
pageTransition: {
name: 'fade',
mode: 'out-in' // 默认
},
layoutTransition: {
name: 'slide',
mode: 'out-in' // 默认
}
}
})
name 属性，则还必须相应地重命名 CSS 类。要覆盖全局过渡属性，请使用 definePageMeta 为单个 Nuxt 页面定义页面或布局过渡，并覆盖在 nuxt.config 文件中定义的任何页面或布局过渡。
<script setup lang="ts">
definePageMeta({
pageTransition: {
name: 'bounce',
mode: 'out-in' // 默认
}
})
</script>
禁用过渡
pageTransition 和 layoutTransition 可以为特定路由禁用：
<script setup lang="ts">
definePageMeta({
pageTransition: false,
layoutTransition: false
})
</script>
或者在 nuxt.config 中全局禁用：
export default defineNuxtConfig({
app: {
pageTransition: false,
layoutTransition: false
}
})
JavaScript 钩子
对于高级用例，您可以使用 JavaScript 钩子为您的 Nuxt 页面创建高度动态和自定义的过渡。
这为使用 JavaScript 动画库，如 GSAP 提供了完美的用例。
<script setup lang="ts">
definePageMeta({
pageTransition: {
name: 'custom-flip',
mode: 'out-in',
onBeforeEnter: (el) => {
console.log('进入之前...')
},
onEnter: (el, done) => {},
onAfterEnter: (el) => {}
}
})
</script>
Transition 组件中使用。动态过渡
要使用条件逻辑应用动态过渡，您可以利用内联 中间件 为 to.meta.pageTransition 指定不同的过渡名称。
<script setup lang="ts">
definePageMeta({
pageTransition: {
name: 'slide-right',
mode: 'out-in'
},
middleware (to, from) {
if (to.meta.pageTransition && typeof to.meta.pageTransition !== 'boolean')
to.meta.pageTransition.name = +to.params.id! > +from.params.id! ? 'slide-left' : 'slide-right'
}
})
</script>
<template>
<h1>#{{ $route.params.id }}</h1>
</template>
<style>
.slide-left-enter-active,
.slide-left-leave-active,
.slide-right-enter-active,
.slide-right-leave-active {
transition: all 0.2s;
}
.slide-left-enter-from {
opacity: 0;
transform: translate(50px, 0);
}
.slide-left-leave-to {
opacity: 0;
transform: translate(-50px, 0);
}
.slide-right-enter-from {
opacity: 0;
transform: translate(-50px, 0);
}
.slide-right-leave-to {
opacity: 0;
transform: translate(50px, 0);
}
</style>
该页面在转到下一个 id 时应用 slide-left 过渡，而在转到上一个 id 时应用 slide-right：
与 NuxtPage 的过渡
当在 app.vue 中使用 <NuxtPage /> 时，可以使用 transition 属性配置全局过渡。
<template>
<div>
<NuxtLayout>
<NuxtPage :transition="{
name: 'bounce',
mode: 'out-in'
}" />
</NuxtLayout>
</div>
</template>
definePageMeta 在单个页面上覆盖。视图过渡 API（实验性）
Nuxt 提供了 视图过渡 API 的实验性实现（详见 MDN）。这是实现本地浏览器过渡的一种激动人心的新方式，这种过渡可以在不同页面之间过渡不相关的元素。
您可以访问 https://nuxt-view-transitions.surge.sh 查看演示以及 StackBlitz 上的源代码。
Nuxt 集成正在积极开发中，但可以通过在配置文件中启用 experimental.viewTransition 选项来启用：
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
可能的值为：false、true 或 'always'。
如果设置为 true，当用户的浏览器符合 prefers-reduced-motion: reduce 时，Nuxt 将不应用过渡（推荐）。如果设置为 always，Nuxt 将始终应用过渡，并由您决定是否尊重用户的偏好。
默认情况下，视图过渡在所有 页面 上启用，但您可以设置不同的全局默认值。
export default defineNuxtConfig({
app: {
// 全局禁用视图过渡，并在每个页面中选择启用
viewTransition: false
},
})
可以通过在页面的 definePageMeta 中设置 viewTransition 键来覆盖默认的 viewTransition 值：
<script setup lang="ts">
definePageMeta({
viewTransition: false
})
</script>
experimental.viewTransition 选项时产生。如果您还使用 Vue 过渡，例如 pageTransition 和 layoutTransition（见上文），以实现与新视图过渡 API 相同的效果，则可以考虑在用户的浏览器支持更新的本地 Web API 时禁用 Vue 过渡。您可以通过创建 ~/middleware/disable-vue-transitions.global.ts，并且内容如下来实现：
export default defineNuxtRouteMiddleware(to => {
if (import.meta.server || !document.startViewTransition) { return }
// 禁用内置 Vue 过渡
to.meta.pageTransition = false
to.meta.layoutTransition = false
})
已知问题
- 如果您在页面设置函数中执行数据获取，您可能需要重新考虑在此时使用此功能。（根据设计，视图过渡在进行时会完全冻结 DOM 更新。）我们正在考虑将视图过渡限制在
<Suspense>解析之前的最后时刻，但目前，您可能需要仔细考虑是否采用此功能。