页面和布局

了解如何将 Nuxt 2 页面和布局迁移到 Nuxt 3。

app.vue

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

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

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

在文档 > 4.x > 指南 > 目录结构 > App 中阅读更多内容。
在文档 > 4.x > 示例 > Hello World 中阅读并编辑实时示例。

迁移

考虑创建一个 app.vue 文件并包含任何需要在应用程序顶层运行一次的逻辑。您可以在此处查看示例。

布局

如果您在应用程序中将布局用于多个页面，则只需进行细微更改。

在 Nuxt 2 中，<Nuxt> 组件在布局中使用以渲染当前页面。在 Nuxt 3 中，布局使用插槽代替，因此您必须将该组件替换为 <slot />。这也允许使用命名插槽和作用域插槽的高级用例。阅读更多关于布局的信息。

您还需要更改如何使用 definePageMeta 编译器宏定义页面使用的布局。布局将使用 kebab-case 命名。因此，app/layouts/customLayout.vue 在您的页面中引用时变为 custom-layout。

迁移

  1. 将 <Nuxt /> 替换为 <slot />
    app/layouts/custom.vue
      <template>
    <div id="app-layout">
      <main>
-       <Nuxt />
+       <slot />
      </main>
    </div>
  </template>
  2. 使用 definePageMeta 选择页面使用的布局。
    app/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 附带了一个可选的 vue-router 集成，它由您的源目录中是否存在 app/pages/ 目录触发。如果您只有一个页面，您不妨考虑将其移动到 app.vue 以获得更轻量的构建。

动态路由

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

  1. 以前使用 _id 定义动态路由参数的地方，现在使用 [id]。
  2. 以前使用 _.vue 定义全捕获路由的地方，现在使用 [...slug].vue。

嵌套路由

在 Nuxt 2 中，您将使用 <Nuxt> 和 <NuxtChild> 定义任何嵌套路由（带有父子组件）。在 Nuxt 3 中，这些已被单个 <NuxtPage> 组件取代。

页面键和 Keep-alive 属性

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

在文档 > 4.x > 指南 > 目录结构 > App > Pages#特殊元数据 中阅读更多内容。

页面和布局过渡

如果您直接在组件选项中定义页面的过渡或布局，现在您需要使用 definePageMeta 来设置过渡。由于 Vue 3，-enter 和 -leave CSS 类已重命名。当在 <slot> 上使用时，<Nuxt> 的 style 属性不再适用于过渡，因此请将样式移动到您的 -active 类中。

在文档 > 4 X > 入门 > 过渡中阅读更多内容。

迁移

  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> 现在是所有链接（甚至是外部链接）的直接替代品。您可以阅读更多关于它的信息，以及如何扩展它以提供您自己的链接组件。

在 文档 > 4 X > API > 组件 > Nuxt Link 中阅读更多信息。

编程式导航

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

请务必始终 await navigateTo 或通过函数返回其结果来链接其结果。
<script>
export default {
  methods: {
    navigate () {
      this.$router.push({
        path: '/search',
        query: {
          name: 'first name',
          type: '1',
        },
      })
    },
  },
}
</script>