mirror of
https://github.com/nuxt/nuxt.git
synced 2025-02-10 18:58:11 +00:00
docs: improve navigateTo docs with clearer structure and examples (#30876)
This commit is contained in:
Alex Liu
GitHub
parent
3756e7271b
commit
2d88d86835
@ -8,16 +8,16 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::note
|
||||
`navigateTo` is available on both client and server side (but not within Nitro routes).
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.
|
||||
|
||||
::tip
|
||||
To send a redirect from a server endpoint, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead.
|
||||
::warning
|
||||
Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
|
||||
::
|
||||
|
||||
::note
|
||||
`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead.
|
||||
::
|
||||
|
||||
### Within a Vue Component
|
||||
@ -52,9 +52,25 @@ export default defineNuxtRouteMiddleware((to, from) => {
|
||||
})
|
||||
```
|
||||
|
||||
When using `navigateTo` within route middleware, you must **return its result** to ensure the middleware execution flow works correctly.
|
||||
|
||||
For example, the following implementation **will not work as expected**:
|
||||
|
||||
```ts
|
||||
export default defineNuxtRouteMiddleware((to, from) => {
|
||||
if (to.path !== '/search') {
|
||||
// ❌ This will not work as expected
|
||||
navigateTo('/search', { redirectCode: 301 })
|
||||
return
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior.
|
||||
|
||||
:read-more{to="/docs/guide/directory-structure/middleware"}
|
||||
|
||||
### External URL
|
||||
### Navigating to an External URL
|
||||
|
||||
The `external` parameter in `navigateTo` influences how navigating to URLs is handled:
|
||||
|
||||
@ -81,7 +97,7 @@ await navigateTo('https://nuxt.com', {
|
||||
</script>
|
||||
```
|
||||
|
||||
### Using open()
|
||||
### Opening a Page in a New Tab
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
@ -101,7 +117,10 @@ await navigateTo('https://nuxt.com', {
|
||||
## Type
|
||||
|
||||
```ts
|
||||
navigateTo(to: RouteLocationRaw | undefined | null, options?: NavigateToOptions) => Promise<void | NavigationFailure> | RouteLocationRaw
|
||||
function navigateTo(
|
||||
to: RouteLocationRaw | undefined | null,
|
||||
options?: NavigateToOptions
|
||||
) => Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw
|
||||
|
||||
interface NavigateToOptions {
|
||||
replace?: boolean
|
||||
@ -109,11 +128,21 @@ interface NavigateToOptions {
|
||||
external?: boolean
|
||||
open?: OpenOptions
|
||||
}
|
||||
```
|
||||
|
||||
::warning
|
||||
Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
|
||||
::
|
||||
type OpenOptions = {
|
||||
target: string
|
||||
windowFeatures?: OpenWindowFeatures
|
||||
}
|
||||
|
||||
type OpenWindowFeatures = {
|
||||
popup?: boolean
|
||||
noopener?: boolean
|
||||
noreferrer?: boolean
|
||||
} & XOR<{ width?: number }, { innerWidth?: number }>
|
||||
& XOR<{ height?: number }, { innerHeight?: number }>
|
||||
& XOR<{ left?: number }, { screenX?: number }>
|
||||
& XOR<{ top?: number }, { screenY?: number }>
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -144,82 +173,58 @@ await navigateTo({ name: 'product', params: { id: 1 } })
|
||||
|
||||
An object accepting the following properties:
|
||||
|
||||
- `replace` (optional)
|
||||
- `replace`
|
||||
|
||||
**Type**: `boolean`
|
||||
- **Type**: `boolean`
|
||||
- **Default**: `false`
|
||||
- By default, `navigateTo` pushes the given route into the Vue Router's instance on the client side.
|
||||
|
||||
**Default**: `false`
|
||||
This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.
|
||||
|
||||
By default, `navigateTo` pushes the given route into the Vue Router's instance on the client side.
|
||||
- `redirectCode`
|
||||
|
||||
This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.
|
||||
- **Type**: `number`
|
||||
- **Default**: `302`
|
||||
|
||||
- `redirectCode` (optional)
|
||||
- `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirection takes place on the server side.
|
||||
|
||||
**Type**: `number`
|
||||
This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permanent redirections.
|
||||
|
||||
**Default**: `302`
|
||||
- `external`
|
||||
|
||||
`navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirection takes place on the server side.
|
||||
- **Type**: `boolean`
|
||||
- **Default**: `false`
|
||||
|
||||
This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permanent redirections.
|
||||
- Allows navigating to an external URL when set to `true`. Otherwise, `navigateTo` will throw an error, as external navigation is not allowed by default.
|
||||
|
||||
- `external` (optional)
|
||||
- `open`
|
||||
|
||||
**Type**: `boolean`
|
||||
|
||||
**Default**: `false`
|
||||
|
||||
Allows navigating to an external URL when set to `true`. Otherwise, `navigateTo` will throw an error, as external navigation is not allowed by default.
|
||||
|
||||
- `open` (optional)
|
||||
|
||||
**Type**: `OpenOptions`
|
||||
|
||||
Allows navigating to the URL using the [open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) method of the window. This option is only applicable on the client side and will be ignored on the server side.
|
||||
|
||||
An object accepting the following properties:
|
||||
|
||||
- `target`
|
||||
|
||||
**Type**: `string`
|
||||
|
||||
**Default**: `'_blank'`
|
||||
|
||||
A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.
|
||||
|
||||
- `windowFeatures` (optional)
|
||||
|
||||
**Type**: `OpenWindowFeatures`
|
||||
- **Type**: `OpenOptions`
|
||||
- Allows navigating to the URL using the [open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) method of the window. This option is only applicable on the client side and will be ignored on the server side.
|
||||
|
||||
An object accepting the following properties:
|
||||
|
||||
- `popup` (optional)
|
||||
- `target`
|
||||
|
||||
**Type**: `boolean`
|
||||
- **Type**: `string`
|
||||
- **Default**: `'_blank'`
|
||||
|
||||
- `width` or `innerWidth` (optional)
|
||||
- A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.
|
||||
|
||||
**Type**: `number`
|
||||
- `windowFeatures`
|
||||
|
||||
- `height` or `innerHeight` (optional)
|
||||
- **Type**: `OpenWindowFeatures`
|
||||
|
||||
**Type**: `number`
|
||||
- An object accepting the following properties:
|
||||
|
||||
- `left` or `screenX` (optional)
|
||||
| Property | Type | Description |
|
||||
|----------|---------|--------------|
|
||||
| `popup` | `boolean` | Requests a minimal popup window instead of a new tab, with UI features decided by the browser. |
|
||||
| `width` or `innerWidth` | `number` | Specifies the content area's width (minimum 100 pixels), including scrollbars. |
|
||||
| `height` or `innerHeight` | `number` | Specifies the content area's height (minimum 100 pixels), including scrollbars. |
|
||||
| `left` or `screenX` | `number` | Sets the horizontal position of the new window relative to the left edge of the screen. |
|
||||
| `top` or `screenY` | `number` | Sets the vertical position of the new window relative to the top edge of the screen. |
|
||||
| `noopener` | `boolean` | Prevents the new window from accessing the originating window via `window.opener`. |
|
||||
| `noreferrer` | `boolean` | Prevents the Referer header from being sent and implicitly enables `noopener`. |
|
||||
|
||||
**Type**: `number`
|
||||
|
||||
- `top` or `screenY` (optional)
|
||||
|
||||
**Type**: `number`
|
||||
|
||||
- `noopener` (optional)
|
||||
|
||||
**Type**: `boolean`
|
||||
|
||||
- `noreferrer` (optional)
|
||||
|
||||
**Type**: `boolean`
|
||||
|
||||
Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) for more detailed information on the **windowFeatures** properties.
|
||||
Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#windowfeatures) for more detailed information on the **windowFeatures** properties.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user