docs(routing): improvements (#3664)

This commit is contained in:
Sébastien Chopin 2022-03-15 10:59:27 +01:00 committed by GitHub
parent 3ded2e35ad
commit 58a46f2270
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 84 additions and 39 deletions

View File

@ -1,10 +1,8 @@
# Routing # NuxtLink
## `<NuxtLink>`
Nuxt provides `<NuxtLink>` component to handle any kind of links within your application. Nuxt provides `<NuxtLink>` component to handle any kind of links within your application.
`<NuxtLink>` component is a drop-in replacement for both Vue Router's `<RouterLink />` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.) `<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
## Examples ## Examples

View File

@ -6,22 +6,65 @@ head.title: Pages directory
# Pages directory # Pages directory
Nuxt provides a file-based routing to create routes within your web application using [Vue Router](https://router.vuejs.org) under the hood.
::alert{type="info"} ::alert{type="info"}
The `pages/` directory is optional, meaning that if you only use [app.vue](/docs/directory-structure/app), `vue-router` won't be included, reducing your application's bundle size. This directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [app.vue](/docs/directory-structure/app), reducing your application's bundle size.
:: ::
Nuxt will automatically integrate [Vue Router](https://router.vuejs.org/) and map `pages/` directory into the routes of your application. ## Usage
Pages are Vue components and can have the `.vue`, `.js`, `.jsx`, `.ts` or `.tsx` extension.
::code-group
```vue [pages/index.vue]
<template>
<h1>Index page</h1>
</template>
```
```ts [pages/index.ts]
// https://vuejs.org/guide/extras/render-function.html
export default defineComponent({
render () {
return h('h1', 'Index page')
}
})
```
```ts [pages/index.tsx]
// https://vuejs.org/guide/extras/render-function.html#jsx-tsx
export default defineComponent({
render () {
return <h1>Index page</h1>
}
})
```
::
The `pages/index.vue` file will be mapped to the `/` route of your application.
If you are using [app.vue](/docs/directory-structure/app), make sure to use the `<NuxtPage/>` component to display the current page:
```vue [app.vue]
<template>
<div>
<!-- Markup shared across all pages, ex: NavBar -->
<NuxtPage />
</div>
</template>
```
::alert{type=warning} ::alert{type=warning}
Unlike components, your pages must have a single root element to allow Nuxt to apply route transitions between pages. Note that pages **must have a single root element** to allow route transitions between pages.
:: ::
## Dynamic Routes ## Dynamic Routes
If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory. If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.
If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path, and thus it doesn't support any non-dynamic text.
### Example ### Example
```bash ```bash
@ -33,17 +76,16 @@ If you need a catch-all route, you create it by using a file named like `[...slu
Given the example above, you can access group/id within your component via the `$route` object: Given the example above, you can access group/id within your component via the `$route` object:
```vue ```vue [pages/users-[group]/[id].vue]
<template> <template>
{{ $route.params.group }} <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
{{ $route.params.id }}
</template> </template>
``` ```
Navigating to `/users-admins/123` would render: Navigating to `/users-admins/123` would render:
```text ```html
admins 123 <p>admins - 123</p>
``` ```
If you want to access the route using Composition API, there is a global `useRoute` function that will allow you to access the route just like `this.$route` in the Options API. If you want to access the route using Composition API, there is a global `useRoute` function that will allow you to access the route just like `this.$route` in the Options API.
@ -58,36 +100,22 @@ if (route.params.group === 'admins' && !route.params.id) {
</script> </script>
``` ```
## Navigation ## Catch all route
To navigate between pages of your app, you should use the  `<NuxtLink>` component. This component is included with Nuxt and therefore you don't have to import it as you do with other components. It is similar to the HTML `<a>` tag except that instead of using a `href="/about"` you use `to="/about"`. If you've used `vue-router` before, you can think of `<NuxtLink>` as a replacement for `<RouterLink>`. If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path.
A simple link to the `index.vue` page in your `pages` folder: ```vue [pages/[...slug].vue]
```html
<template> <template>
<NuxtLink to="/">Home page</NuxtLink> <p>{{ $route.params.slug }}</p>
</template> </template>
``` ```
The `<NuxtLink>` component should be used for all internal links. That means for all links to the pages within your site you should use `<NuxtLink>`. The `<a>` tag should be used for all external links. That means if you have links to other websites you should use the `<a>` tag for those. Navigating to `/hello/world` would render:
```html ```html
<template> <p>["hello", "world"]</p>
<div>
<h1>Home page</h1>
<NuxtLink to="/about">
About (internal link that belongs to the Nuxt App)
</NuxtLink>
<a href="https://nuxtjs.org">External Link to another page</a>
</div>
</template>
``` ```
::alert{type="info"}
If you want to know more about `<RouterLink>`, read the [Vue Router documentation](https://router.vuejs.org/api/#router-link) for more information.
::
## Nested Routes ## Nested Routes
It is possible to display [nested routes](https://next.router.vuejs.org/guide/essentials/nested-routes.html) with `<NuxtPage>`. It is possible to display [nested routes](https://next.router.vuejs.org/guide/essentials/nested-routes.html) with `<NuxtPage>`.
@ -171,6 +199,7 @@ This data can then be accessed throughout the rest of your app from the `route.m
```vue ```vue
<script setup> <script setup>
const route = useRoute() const route = useRoute()
console.log(route.meta.title) // My home page console.log(route.meta.title) // My home page
</script> </script>
``` ```
@ -186,7 +215,7 @@ import { someData } from '~/utils/example'
const title = ref('') const title = ref('')
definePageMeta({ definePageMeta({
title, title, // This will create an error
someData someData
}) })
</script> </script>
@ -215,3 +244,21 @@ You can define middleware to apply before loading this page. It will be merged w
#### `layoutTransition` and `pageTransition` #### `layoutTransition` and `pageTransition`
You can define transition properties for the `<transition>` components that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. [More about transitions](https://vuejs.org/guide/built-ins/transition.html#transition). You can define transition properties for the `<transition>` components that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. [More about transitions](https://vuejs.org/guide/built-ins/transition.html#transition).
## Navigation
To navigate between pages of your app, you should use the [`<NuxtLink>`](/docs/usage/nuxt-link) component.
This component is included with Nuxt and therefore you don't have to import it as you do with other components.
A simple link to the `index.vue` page in your `pages` folder:
```html
<template>
<NuxtLink to="/">Home page</NuxtLink>
</template>
```
::alert{type="info"}
Learn more about [`<NuxtLink>`](/docs/usage/nuxt-link) usage.
::

View File

@ -11150,10 +11150,10 @@ untyped@^0.2.5, untyped@^0.2.8, untyped@^0.2.9:
resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.2.9.tgz#3e3df96a303dec3e2eda55fcbdc02e2ab468683d" resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.2.9.tgz#3e3df96a303dec3e2eda55fcbdc02e2ab468683d"
integrity sha512-8d8V+q/y5CGzV+IYnoOCMjrK+NSNp1HKO8iPQ+bV4rBP8knPIme3+j/bpej8IuMnEMxOJZNptXNOXCx7w+VJxQ== integrity sha512-8d8V+q/y5CGzV+IYnoOCMjrK+NSNp1HKO8iPQ+bV4rBP8knPIme3+j/bpej8IuMnEMxOJZNptXNOXCx7w+VJxQ==
untyped@^0.3.0: untyped@^0.4.2:
version "0.3.0" version "0.4.2"
resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.3.0.tgz#854df4dec055cc6a0a2217aa2d20152277b6ada9" resolved "https://registry.yarnpkg.com/untyped/-/untyped-0.4.2.tgz#302e53b1733ff383749342b06f38277af97516ad"
integrity sha512-n4M5/T1wWlHFmohk0EhS+yM7W/h5dOtQldOV3MVEbZY1fTy5A47UL8+d8GLW1iwmaAwNrM5ERy3qe1k0T/Yc7A== integrity sha512-akHdcDop+tvtwPQxrbDfGf6zfQUgMjJXA8hXYYxcnmH6NnuMQatiY9wYDZ+jkUCcWuctb70f/QBYmbMsJpl48g==
upath@^1.1.1: upath@^1.1.1:
version "1.2.0" version "1.2.0"