---
title: "<NuxtPage>"
description: "<NuxtPage> 组件用于显示位于 pages/ 目录下的页面。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-page"
---
# <NuxtPage>

> <NuxtPage> 组件用于显示位于 pages/ 目录下的页面。

`<NuxtPage>` 是 Nuxt 内置组件。它可以显示位于 [`app/pages/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages) 目录中的顶级页面或嵌套页面。

<note>

`<NuxtPage>` 是对 Vue Router 中的 [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) 的封装。应当使用 `<NuxtPage>` 而不是 `<RouterView>`，因为前者会额外处理内部状态。否则，`useRoute()` 可能会返回不正确的路径。

</note>

`<NuxtPage>` 包含以下组件：

```vue
<template>
  <RouterView v-slot="{ Component }">
    <!-- 可选，在使用过渡时 -->
    <Transition>
      <!-- 可选，在使用状态保持时 -->
      <KeepAlive>
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </KeepAlive>
    </Transition>
  </RouterView>
</template>
```

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

<warning>

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

</warning>

由于 `<NuxtPage>` 在内部使用了 `<Suspense>`，因此页面切换期间的组件生命周期行为与典型的 Vue 应用有所不同。

在典型的 Vue 应用中，新页面组件只有在上一个组件完全卸载之后才会被挂载。然而在 Nuxt 中，受 Vue `<Suspense>` 的实现方式影响，新页面组件会在上一个组件卸载之前就被挂载。

## 属性

- `name`: 告知 `<RouterView>` 在匹配路由记录的 components 选项中渲染具有对应名称的组件。有关 `name@view.vue` 文件名约定，请参阅[命名视图](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages#named-views)。

  - type: `string`
- `route`: 已解析其所有组件的路由位置。

  - type: `RouteLocationNormalized`
- `pageKey`: 控制 `NuxtPage` 组件何时重新渲染。

  - type: `string` 或 `function`
- `transition`: 为所有使用 `NuxtPage` 组件渲染的页面定义全局过渡效果。

  - type: `boolean` 或 [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
- `keepalive`: 控制使用 `NuxtPage` 组件渲染的页面是否保留状态。

  - type: `boolean` 或 [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)

<tip>

Nuxt 会自动通过扫描 `/pages` 目录中发现并渲染的所有 Vue 组件文件来解析 `name` 和 `route`。

</tip>

## 示例

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

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

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

```html
<NuxtPage :page-key="route => route.fullPath" />
```

<warning>

不要在此处使用 `$route` 对象，因为它可能会导致 `<NuxtPage>` 在与 `<Suspense>` 一起渲染页面时出现问题。

</warning>

或者，可以在 `/pages` 目录中的 Vue 组件的 `<script>` 部分通过 [`definePageMeta`](https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta) 将 `pageKey` 作为 `key` 值传入。

```vue [app/pages/my-page.vue]
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
})
</script>
```

<link-example to="https://nuxt.zhcndoc.com/docs/4.x/examples/routing/pages">



</link-example>

## 页面引用

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

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

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

<template>
  <NuxtPage ref="page" />
</template>
```

```vue [my-page.vue]
<script setup lang="ts">
const foo = () => {
  console.log('foo 方法被调用')
}

defineExpose({
  foo,
})
</script>
```

## 自定义属性

`<NuxtPage>` 还接受你可能需要向下传递的自定义属性。

例如，在下面的示例中，`foobar` 的值会传递到 `NuxtPage` 组件，然后传递到页面组件。

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

我们可以在页面组件中访问 `foobar` prop：

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

console.log(props.foobar) // 输出：123
```

如果你没有使用 `defineProps` 定义该 prop，传递给 `NuxtPage` 的任何 props 仍然可以直接从页面的 `attrs` 中访问：

```vue [app/pages/page.vue]
<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // 输出：123
</script>
```

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages">



</read-more>

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/page.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.