Zengtudor/Nuxt
1
0
Fork 0
mirror of https://github.com/nuxt/nuxt.git synced 2025-02-11 03:08:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve navigateTo docs with clearer structure and examples (#30876)

Browse Source
This commit is contained in:
Alex Liu 2025-02-08 17:08:38 +08:00 committed by GitHub
parent 3756e7271b
commit 2d88d86835
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 76 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
docs/3.api/3.utils/navigate-to.md
View File

@ -8,16 +8,16 @@ links:
size: xs size: xs
--- ---
::note
`navigateTo` is available on both client and server side (but not within Nitro routes).
::
## Usage ## 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. `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 ::warning
To send a redirect from a server endpoint, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead. 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 ### 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"} :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: The `external` parameter in `navigateTo` influences how navigating to URLs is handled:
@ -81,7 +97,7 @@ await navigateTo('https://nuxt.com', {
</script> </script>
``` ```
### Using open() ### Opening a Page in a New Tab
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
@ -101,7 +117,10 @@ await navigateTo('https://nuxt.com', {
## Type ## Type
```ts ```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 { interface NavigateToOptions {
replace?: boolean replace?: boolean
@ -109,11 +128,21 @@ interface NavigateToOptions {
external?: boolean external?: boolean
open?: OpenOptions open?: OpenOptions
} }
```
::warning type OpenOptions = {
Make sure to always use `await` or `return` on result of `navigateTo` when calling it. 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 ## Parameters
@ -144,82 +173,58 @@ await navigateTo({ name: 'product', params: { id: 1 } })
An object accepting the following properties: 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` - **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.
**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`
An object accepting the following properties: 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` Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#windowfeatures) for more detailed information on the **windowFeatures** properties.
- `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.