v3
GitHub

页面和布局

学习如何从 Nuxt 2 迁移到 Nuxt 3 的页面和布局。

app.vue

Nuxt 3 通过 ~/app.vue 为您的应用程序提供了一个中央入口点。

如果您的源目录中没有 app.vue 文件，Nuxt 会使用它自己的默认版本。

此文件是放置任何需要在应用启动时运行一次的自定义代码以及出现在应用每个页面上的任何组件的绝佳位置。例如，如果您只有一个布局，可以将其移到 app.vue 中。

Read more in Docs > Guide > Directory Structure > App.
Read and edit a live example in Docs > Examples > Hello World.

迁移

考虑创建一个 app.vue 文件并包含需要在应用顶层运行的一次性逻辑。您可以查看这里的示例。

布局

如果您的应用为多个页面使用布局，所需更改非常少。

在 Nuxt 2 中，布局内使用 <Nuxt> 组件渲染当前页面。在 Nuxt 3 中，布局改为使用插槽，因此您必须将该组件替换为 <slot />。这也支持带命名和作用域插槽的高级用例。了解更多关于布局。

您还需要更改页面中使用布局的定义方式，使用 definePageMeta 编译宏设置布局。布局名称将采用短横线命名法(kebab-case)。例如，layouts/customLayout.vue 在页面中引用时变为 custom-layout。

迁移

  1. 将 <Nuxt /> 替换为 <slot />
    layouts/custom.vue
      <template>
    <div id="app-layout">
      <main>
-       <Nuxt />
+       <slot />
      </main>
    </div>
  </template>
  2. 使用 definePageMeta 选择页面使用的布局。
    pages/index.vue
    + <script setup>
+ definePageMeta({
+   layout: 'custom'
+ })
- <script>
- export default {
-   layout: 'custom'
- }
  </script>
  3. 将 ~/layouts/_error.vue 移动到 ~/error.vue。详见错误处理文档。如果您想确保此页面使用布局，可以直接在 error.vue 中使用 <NuxtLayout>：
    error.vue
    <template>
  <div>
    <NuxtLayout name="default">
      <!-- -->
    </NuxtLayout>
  </div>
</template>

页面

Nuxt 3 通过检测源目录中是否存在 pages/ 目录，提供了可选的 vue-router 集成。如果您只有单一页面，可以考虑将其移到 app.vue 以减小构建体积。

动态路由

Nuxt 3 定义动态路由的格式与 Nuxt 2 略有不同，因此您可能需要重命名 pages/ 目录中的某些文件。

  1. 之前使用 _id 定义动态路由参数，现在改为使用 [id]。
  2. 之前使用 _.vue 定义通配路由，现在改为 [...slug].vue。

嵌套路由

在 Nuxt 2 中，您会使用 <Nuxt> 和 <NuxtChild> 定义父子组件的嵌套路由。Nuxt 3 中，这些已被单个 <NuxtPage> 组件替代。

页面键和 Keep-alive 属性

如果您向 <Nuxt> 传递自定义页面键或 keep-alive 属性，现在需使用 definePageMeta 设置这些选项。

Read more in Docs > Guide > Directory Structure > Pages#special Metadata.

页面与布局切换动画

如果您曾在组件选项中直接定义页面或布局的过渡动画，现在需使用 definePageMeta 设置该过渡。自 Vue 3 起，-enter 和 -leave CSS 类名已重命名。在 <slot> 上使用 <Nuxt> 的 style 属性不再应用于过渡，请将样式移至 -active 类。

Read more in Docs > Getting Started > Transitions.

迁移

  1. 重命名所有带有动态参数的页面，使其符合新格式。
  2. 更新 <Nuxt> 和 <NuxtChild> 为 <NuxtPage>。
  3. 如果使用组合式 API，您还可以将 this.$route 和 this.$router 迁移为使用 useRoute 和 useRouter 组合函数。

示例：动态路由

- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/_user.vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/_user/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/_.vue
- Usage: params.pathMatch

示例：嵌套路由和 definePageMeta

<template>
  <div>
    <NuxtChild keep-alive :keep-alive-props="{ exclude: ['modal'] }" :nuxt-child-key="$route.slug" />
  </div>
</template>

<script>
export default {
  transition: 'page' // or { name: 'page' }
}
</script>

<NuxtLink> 组件

全局的 NuxtLink 组件的大部分语法和功能保持不变。如果您之前使用过快捷方式 <NLink>，建议更新为使用 <NuxtLink>。

<NuxtLink> 现在可作为所有链接的免替换组件，即使是外部链接。您可以阅读更多关于它的信息，以及如何扩展以提供您自己的链接组件。

Read more in Docs > API > Components > Nuxt Link.

编程式导航

从 Nuxt 2 迁移到 Nuxt 3 时，您需要更新编程式导航的方式。Nuxt 2 中，您可以通过 this.$router 访问底层 Vue Router。Nuxt 3 中，您可以使用 navigateTo() 工具方法，将路由和参数传递给 Vue Router。

请务必始终对 navigateTo 使用 await，或在函数中返回其结果以链式调用。
<script>
export default {
  methods: {
    navigate(){
      this.$router.push({
        path: '/search',
        query: {
          name: 'first name',
          type: '1'
        }
      })
    }
  }
}
</script>