This repository has been archived by the owner on Apr 6, 2023. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(api): add
definePageMeta
util (#6931)
Co-authored-by: Daniel Roe <daniel@roe.dev> Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com>
- Loading branch information
1 parent
0c49e8c
commit c79d2bc
Showing
1 changed file
with
147 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,152 @@ | ||
# `definePageMeta` | ||
|
||
::ReadMore{link="/guide/features/routing"} | ||
`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the `pages/` directory (unless [set otherwise](https://v3.nuxtjs.org/api/configuration/nuxt.config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application. | ||
|
||
```vue [pages/some-page.vue] | ||
<script setup> | ||
definePageMeta({ | ||
title: 'Articles' | ||
}) | ||
</script> | ||
``` | ||
|
||
::ReadMore{link="/guide/directory-structure/pages/#page-metadata"} | ||
:: | ||
|
||
::NeedContribution | ||
## Type | ||
|
||
```ts | ||
definePageMeta(meta: PageMeta) => void | ||
|
||
interface PageMeta { | ||
pageTransition?: boolean | TransitionProps | ||
layoutTransition?: boolean | TransitionProps | ||
key?: false | string | ((route: RouteLocationNormalizedLoaded) => string) | ||
keepalive?: boolean | KeepAliveProps | ||
layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey> | ||
middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard> | ||
[key: string]: any | ||
} | ||
``` | ||
|
||
## Parameters | ||
|
||
### `meta` | ||
|
||
- **Type**: `PageMeta` | ||
|
||
An object accepting the following page metadata: | ||
|
||
**`pageTransition`** | ||
|
||
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) | ||
|
||
Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition. | ||
|
||
**`layoutTransition`** | ||
|
||
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) | ||
|
||
Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition. | ||
|
||
**`key`** | ||
|
||
- **Type**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)` | ||
|
||
Set `key` value when you need more control over when the `<NuxtPage>` component is re-rendered. | ||
|
||
**`keepalive`** | ||
|
||
- **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) | ||
|
||
Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) for a fine-grained control. | ||
|
||
**`layout`** | ||
|
||
- **Type**: `false` | `LayoutKey` | `Ref<LayoutKey>` | `ComputedRef<LayoutKey>` | ||
|
||
Set a static or dynamic name of the layout for each route. This can be set to `false` in case the default layout needs to be disabled. | ||
|
||
**`middleware`** | ||
|
||
- **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/NavigationGuard.html#navigationguard) | `Array<MiddlewareKey | NavigationGuard>` | ||
|
||
Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/directory-structure/middleware). | ||
|
||
**`[key: string]`** | ||
|
||
- **Type**: `any` | ||
|
||
Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/guide/directory-structure/pages/#typing-custom-metadata). | ||
|
||
## Examples | ||
|
||
### Basic Usage | ||
|
||
The example below demonstrates: | ||
|
||
- how `key` can be a function that returns a value; | ||
- how `keepalive` property makes sure that the `<modal>` component is not cached when switching between multiple components; | ||
- adding `pageType` as a custom property: | ||
|
||
```vue [pages/some-page.vue] | ||
<script setup> | ||
definePageMeta({ | ||
key: (route) => route.fullPath, | ||
keepalive: { | ||
exclude: ['modal'] | ||
}, | ||
pageType: 'Checkout' | ||
}) | ||
</script> | ||
``` | ||
|
||
### Defining Middleware | ||
|
||
The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory: | ||
|
||
```vue [pages/some-page.vue] | ||
<script setup> | ||
definePageMeta({ | ||
// define middleware as a function | ||
middleware: [ | ||
function (to, from) { | ||
const auth = useState('auth') | ||
if (!auth.value.authenticated) { | ||
return navigateTo('/login') | ||
} | ||
return navigateTo('/checkout') | ||
} | ||
], | ||
// ... or a string | ||
middleware: 'auth' | ||
// ... or multiple strings | ||
middleware: ['auth', 'another-named-middleware'] | ||
}) | ||
</script> | ||
``` | ||
|
||
### Defining Layout | ||
|
||
You can define the layout that matches the layout's file name located (by default) in the `layouts/` directory. You can also disable the layout by setting the `layout` to `false`: | ||
|
||
```vue [pages/some-page.vue] | ||
<script setup> | ||
definePageMeta({ | ||
// set custom layout | ||
layout: 'admin' | ||
// ... or disable a default layout | ||
layout: false | ||
}) | ||
</script> | ||
``` | ||
|
||
::ReadMore{link="/guide/features/routing"} | ||
:: |