diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts index 70042ff08..98994e1a9 100644 --- a/packages/docs/.vitepress/config/en.ts +++ b/packages/docs/.vitepress/config/en.ts @@ -84,6 +84,10 @@ export const enConfig: LocaleSpecificConfig = { text: "Routes' Matching Syntax", link: '/guide/essentials/route-matching-syntax.html', }, + { + text: 'Named Routes', + link: '/guide/essentials/named-routes.html', + }, { text: 'Nested Routes', link: '/guide/essentials/nested-routes.html', @@ -92,10 +96,6 @@ export const enConfig: LocaleSpecificConfig = { text: 'Programmatic Navigation', link: '/guide/essentials/navigation.html', }, - { - text: 'Named Routes', - link: '/guide/essentials/named-routes.html', - }, { text: 'Named Views', link: '/guide/essentials/named-views.html', diff --git a/packages/docs/guide/essentials/named-routes.md b/packages/docs/guide/essentials/named-routes.md index 51d1cda1e..d1e27aae7 100644 --- a/packages/docs/guide/essentials/named-routes.md +++ b/packages/docs/guide/essentials/named-routes.md @@ -5,39 +5,41 @@ title="Learn about the named routes" /> -Alongside the `path`, you can provide a `name` to any route. This has the following advantages: - -- No hardcoded URLs -- Automatic encoding/decoding of `params` -- Prevents you from having a typo in the url -- Bypassing path ranking (e.g. to display a ) +When creating a route, we can optionally give the route a `name`: ```js const routes = [ { path: '/user/:username', - name: 'user', + name: 'profile', // [!code highlight] component: User } ] ``` -To link to a named route, you can pass an object to the `router-link` component's `to` prop: +We can then use the `name` instead of the `path` when passing the `to` prop to ``: ```vue-html - - User + + User profile ``` -This is the exact same object used programmatically with `router.push()`: +The example above would create a link to `/user/erina`. -```js -router.push({ name: 'user', params: { username: 'erina' } }) -``` +- [See it in the Playground](https://play.vuejs.org/#eNqtVVtP2zAU/itWNqlFauNNIB6iUMEQEps0NjH2tOzBtKY1JLZlO6VTlP++4+PcelnFwyRofe7fubaKCiZk/GyjJBKFVsaRiswNZ45faU1q8mRUQUbrko8yuaPwlRfK/LkV1sHXpGHeq9JxMzScGmT19t5xkMaUaR1vOb9VBe+kntgWXz2Cs06O1LbCTwvRW7knGnEm50paRwIYcrEFd1xlkpBVyCQ5lN74ZOJV0Nom5JcnCFRCM7dKyIiOJkSygsNzBZiBmivAI7l0SUipRvuhCfPge7uWHBiGZPctS0iLJv7T2/YutFFPIt+JjgUJPn7DZ32CtWg7PIZ/4BASg7txKE6gC1VKNx69gw6NTqJJ1HQK5iR1vNA52M+8Yrr6OLuD+AuCtbQpBQYK9Oy6NAZAhLI1KKuKvEc69jSp65Tqw/oh3V7f00P9MsdveOWiecE75DDNhXwhiVMXWVRttYbUWdRpE2xOZ0sHxq1v2jl/a5jQyZ042Mv/HKjvt2aGFTCXFWmnAsTcCMkAxw4SHIjG9E2AUtpUusWyFvyVUGCltBsFmJB2W/dHZCHWswdYLwJ/XiulnrNr323zcQeodthDuAHTgmm4aEqCH1zsrBHYLIISheyyqD9Nnp1FK+e0TSgtpX5ZxrBBtNe4PItP4w8Q07oBN+a2mD4a9erPzDN4bzY1iy5BiS742imV2ynT4l8h9hQvz+Pz+COU/pGCdyrkgm/Qt3ddw/5Cms7CLXsSy50k/dJDT8037QTcuq1kWZ6r1y/Ic6bkHdD5is9fDvCf7SZA/m44ZLfmg+QcM0vugvjmxx3fwLsTFmpRwlwdE95zq/LSYwxqn0q5ANgDPUT7GXsm5PLB3mwcl7ZNygPFaqA+NvL6SOo93NP4bFDF9sfh+LThtgxvkF80fyxxy/Ac7U9i/RcYNWrd). + +Using a `name` has various advantages: -In both cases, the router will navigate to the path `/user/erina`. +- No hardcoded URLs. +- Automatic encoding of `params`. +- Avoids URL typos. +- Bypassing path ranking, e.g. to display a lower-ranked route that matches the same path. -Full example [here](https://github.com/vuejs/vue-router/blob/dev/examples/named-routes/app.js). +Each name **must be unique** across all routes. If you add the same name to multiple routes, the router will only keep the last one. You can read more about this [in the Dynamic Routing](../advanced/dynamic-routing#Removing-routes) section. -Each name **must be unique** across all routes. If you add the same name to multiple routes, the router will only keep the last one. You can read more about this [in the Dynamic Routing](../advanced/dynamic-routing.md#Removing-routes) section. +There are various other parts of Vue Router that can be passed a location, e.g. the methods `router.push()` and `router.replace()`. We'll go into more detail about those methods in the guide to [programmatic navigation](./navigation). Just like the `to` prop, these methods also support passing a location by `name`: + +```js +router.push({ name: 'profile', params: { username: 'erina' } }) +```