pages

Nuxt 提供基于文件的路由功能，用于在你的 Web 应用中创建路由。

为了减少应用的打包体积，该目录是可选的，这意味着如果你只使用 app.vue，则不会包含 vue-router。要强制启用 pages 系统，可以在 nuxt.config 中设置 pages: true，或者使用 app/router.options.ts。

使用方法

Pages 是 Vue 组件，可以使用 Nuxt 支持的任何有效扩展名（默认支持 .vue、.js、.jsx、.mjs、.ts 或 .tsx）。

Nuxt 会自动为 ~/pages/ 目录下的每个页面创建对应的路由。

<template>
  <h1>索引页</h1>
</template>

// https://vue.zhcndoc.com/guide/extras/render-function.html
export default defineComponent({
  render () {
    return h('h1', '索引页')
  }
})

// https://nuxt.com/docs/examples/advanced/jsx
// https://vue.zhcndoc.com/guide/extras/render-function.html#jsx-tsx
export default defineComponent({
  render () {
    return <h1>索引页</h1>
  }
})

pages/index.vue 文件会映射到应用的 / 路由。

如果你使用 app.vue，请确保使用 <NuxtPage/> 组件来显示当前页面：

app.vue

<template>
  <div>
    <!-- 所有页面共享的标记，例如：导航栏 -->
    <NuxtPage />
  </div>
</template>

页面必须有单个根元素，以支持页面间的路由过渡。HTML 注释也被视为元素。

这意味着当路由被服务器端渲染或静态生成时，会正确显示内容，但在客户端导航切换路由时，过渡会失败，页面将不会被渲染。

以下是单根元素页面的示例：

<template>
  <div>
    <!-- 此页面正确地只有一个根元素 -->
    页面内容
  </div>
</template>

<template>
  <!-- 由于此注释，客户端导航切换路由时该页面不会渲染 -->
  <div>页面内容</div>
</template>

<template>
  <div>此页面</div>
  <div>有多个根元素</div>
  <div>客户端导航切换路由时不会渲染</div>
</template>

动态路由

如果在文件名中使用方括号包裹的内容，它将被转换为动态路由参数。你可以在文件名或目录中混合多个参数和非动态文本。

如果想让参数变为_可选_，需用双重方括号包裹，比如 ~/pages/[[slug]]/index.vue 或 ~/pages/[[slug]].vue，这将匹配 / 和 /test 两种路径。

目录结构

-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue

以上例子中，你可以通过 $route 对象访问组件中的 group 和 id：

pages/users-[group]/[id].vue

<template>
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>

访问 /users-admins/123 时会渲染：

<p>admins - 123</p>

如果想在组合式 API 中访问路由，可以使用全局 useRoute 函数，类似选项式 API 中的 this.$route。

<script setup lang="ts">
const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('警告！请确保用户已认证！')
}
</script>

命名的父路由优先于嵌套路由中的动态路由。例如 /foo/hello 路由中，~/pages/foo.vue 会优先于 ~/pages/foo/[slug].vue。
你可以使用 ~/pages/foo/index.vue 和 ~/pages/foo/[slug].vue，实现 /foo 和 /foo/hello 对应不同页面。

通配路由

如果需要通配路由，可使用 [...slug].vue 文件名创建，该路由将匹配该路径下的_所有_路由。

pages/[...slug].vue

<template>
  <p>{{ $route.params.slug }}</p>
</template>

访问 /hello/world 会渲染：

<p>["hello", "world"]</p>

嵌套路由

可以使用 <NuxtPage> 来显示嵌套路由。

示例：

目录结构

-| pages/
---| parent/
-----| child.vue
---| parent.vue

上述结构会生成以下路由：

[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]

要显示 child.vue 组件，需在 pages/parent.vue 内插入 <NuxtPage> 组件：

pages/parent.vue

<template>
  <div>
    <h1>我是父视图</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

pages/parent/child.vue

<script setup lang="ts">
const props = defineProps(['foobar'])

console.log(props.foobar)
</script>

子路由键值

如果想更细粒度控制 <NuxtPage> 的重新渲染（例如为了过渡效果），可通过 pageKey 属性传入字符串或函数，或者通过 definePageMeta 定义 key 值：

pages/parent.vue

<template>
  <div>
    <h1>我是父视图</h1>
    <NuxtPage :page-key="route => route.fullPath" />
  </div>
</template>

或者：

pages/parent/child.vue

<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath
})
</script>

Read and edit a live example in Docs > Examples > Routing > Pages.

路由分组

有时你可能想将一组路由归为一组，但不影响基于文件的路由规则。为此，可以将文件放置在用括号( 和 ) 包裹的文件夹内。

例如：

目录结构

-| pages/
---| index.vue
---| (marketing)/
-----| about.vue
-----| contact.vue

这会生成 /、/about 和 /contact 页面。括号内的 marketing 组不会出现在 URL 结构中。

页面元信息

你可能想为应用中的每个路由定义元信息，可以通过 definePageMeta 宏实现，支持写在 <script> 和 <script setup> 中：

<script setup lang="ts">
definePageMeta({
  title: '我的首页'
})
</script>

该数据可在应用中通过 route.meta 对象获取：

<script setup lang="ts">
const route = useRoute()

console.log(route.meta.title) // 我的首页
</script>

如果使用嵌套路由，所有路由的页面元信息将合并为一个对象。关于路由元信息更多内容，可参考 vue-router 文档。

类似于 defineEmits 或 defineProps（参考 Vue 文档），definePageMeta 是一个编译器宏，会被编译器移除，因此不能在组件内直接引用。它传递的元信息会被提升出组件。因此，页面元信息对象不能引用组件自身，但可以引用导入的绑定和本地定义的纯函数。

确保不要引用任何响应式数据或带有副作用的函数，否则可能导致意外行为。

<script setup lang="ts">
import { someData } from '~/utils/example'

function validateIdParam(route) {
  return route.params.id && !isNaN(Number(route.params.id))
}

const title = ref('')

definePageMeta({
  validate: validateIdParam,
  someData,
  title,    // 不要这么做，ref 会被提升出组件
})
</script>

你可以在你的 nuxt.config 中为此属性设置默认值。

declare module '#app' {
  interface PageMeta {
    pageType?: string
  }
}

// 扩展类型时确保导入/导出语句以避免模块转为全局
export {}

编程式导航

Nuxt 支持使用 navigateTo() 实用方法进行编程式导航。使用它可以根据用户输入动态跳转页面。下面示例展示了一个名为 navigate() 的方法，在用户提交搜索表单时调用。

务必 awaitnavigateTo 的结果，或在函数中返回它。

<script setup lang="ts">
const name = ref('');
const type = ref(1);

function navigate(){
  return navigateTo({
    path: '/search',
    query: {
      name: name.value,
      type: type.value
    }
  })
}
</script>

目录结构

-| some-app/
---| nuxt.config.ts
---| pages/
-----| app-page.vue
-| nuxt.config.ts

some-app/nuxt.config.ts

// some-app/nuxt.config.ts
export default defineNuxtConfig({
})

nuxt.config.ts

export default defineNuxtConfig({
  extends: ['./some-app'],
})

Read more in Docs > Guide > Going Further > Layers.

Was this helpful?

报告问题或者在 GitHub 上编辑此页面

node_modules

包管理器将项目的依赖存储在 node_modules/ 目录中。

plugins

Nuxt 有一个插件系统，可以在创建 Vue 应用时使用 Vue 插件及更多功能。

pages

使用方法

动态路由

通配路由

嵌套路由

子路由键值

路由分组

页面元信息

特殊元信息

`alias`

`keepalive`

`key`

`layout`

`layoutTransition` 和 `pageTransition`

`middleware`

`name`

`path`

`props`

自定义元信息的类型定义

导航

编程式导航

仅客户端页面

仅服务端页面

自定义路由

多 pages 目录