v3
GitHub

<NuxtPage>

源码
<NuxtPage> 组件是显示位于 pages/ 目录中的页面所必需的。

<NuxtPage> 是 Nuxt 内置的组件。它允许你显示位于 pages/ 目录中的顶级或嵌套页面。

<NuxtPage> 是 Vue Router 中 <RouterView> 的包装组件。应当使用它替代 <RouterView>，因为它会额外处理内部状态。否则，useRoute() 可能返回错误的路径。

<NuxtPage> 包含以下组件：

<template>
  <RouterView #default="{ Component }">
    <!-- 可选，当使用过渡动画时 -->
    <Transition>
      <!-- 可选，当使用 keep-alive 时 -->
      <KeepAlive>
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </KeepAlive>
    </Transition>
  </RouterView>
</template>

默认情况下，Nuxt 不启用 <Transition> 和 <KeepAlive>。你可以在 nuxt.config 文件中启用它们，或者在 <NuxtPage> 上设置 transition 和 keepalive 属性。如果想为某个特定页面定义，可以在该页面组件中的 definePageMeta 中设置。

如果你在页面组件中启用了 <Transition>，请确保页面只有一个根元素。

由于 <NuxtPage> 底层使用了 <Suspense>，页面切换时组件的生命周期行为与普通的 Vue 应用不同。

在典型的 Vue 应用中，新的页面组件是在前一个完全卸载之后才挂载的。但在 Nuxt 中，由于 Vue <Suspense> 的实现机制，新的页面组件会在前一个页面卸载之前就先挂载。

Props

  • name：告知 <RouterView> 渲染匹配路由记录中对应名称的组件。
    • 类型：string
  • route：带有所有已解析组件的路由位置对象。
    • 类型：RouteLocationNormalized
  • pageKey：控制 NuxtPage 组件何时重新渲染。
    • 类型：string 或 function
  • transition：定义所有通过 NuxtPage 渲染的页面的全局过渡效果。
  • keepalive：控制通过 NuxtPage 渲染的页面状态是否保留。
Nuxt 会自动通过扫描并渲染 /pages 目录内所有 Vue 组件文件来解析 name 和 route。

示例

例如，如果你传入一个永远不变的 key，<NuxtPage> 组件只会渲染一次 —— 即首次挂载时。

app.vue
<template>
  <NuxtPage page-key="static" />
</template>

你也可以基于当前路由使用动态 key：

<NuxtPage :page-key="route => route.fullPath" />
不要在这里使用 $route 对象，因为它可能导致 <NuxtPage> 使用 <Suspense> 时渲染页面出现问题。

另外，你也可以通过位于 /pages 目录中 Vue 组件 <script> 部分的 definePageMeta 传递 pageKey 作为 key 值。

pages/my-page.vue
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath
})
</script>
Read and edit a live example in Docs > Examples > Routing > Pages.

页面组件的 Ref

要获取页面组件的 ref，可以通过 ref.value.pageRef 访问。

app.vue
<script setup lang="ts">
const page = ref()

function logFoo () {
  page.value.pageRef.foo()
}
</script>

<template>
  <NuxtPage ref="page" />
</template>
my-page.vue
<script setup lang="ts">
const foo = () => {
  console.log('foo 方法被调用')
}

defineExpose({
  foo,
})
</script>

自定义 Props

<NuxtPage> 也支持传递自定义 props，方便你将其逐级向下传递。

例如，在下面这个例子中，foobar 的值会传给 NuxtPage，然后传递给页面组件。

app.vue
<template>
  <NuxtPage :foobar="123" />
</template>

你可以在页面组件中访问 foobar prop：

pages/page.vue
<script setup lang="ts">
const props = defineProps<{ foobar: number }>()

console.log(props.foobar) // 输出: 123

如果没有用 defineProps 明确定义 prop，传给 NuxtPage 的任何 props 仍然可以从页面组件的 attrs 直接访问：

pages/page.vue
<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // 输出: 123
</script>
Read more in Docs > Guide > Directory Structure > Pages.