用法
navigateTo 在服务器端和客户端均可使用。它可以在 Nuxt 上下文 中使用，也可以直接使用，以执行页面导航。
调用
navigateTo 时，请务必在其结果上使用 await 或 return。navigateTo 不能在 Nitro 路由中使用。要在 Nitro 路由中执行服务器端重定向，请改用 sendRedirect。在 Vue 组件中
<script setup lang="ts">
// 将 'to' 作为字符串传递
await navigateTo('/search')
// ... 或者作为路由对象
await navigateTo({ path: '/search' })
// ... 或者作为带有查询参数的路由对象
await navigateTo({
path: '/search',
query: {
page: 1,
sort: 'asc'
}
})
</script>
在路由中间件中
export default defineNuxtRouteMiddleware((to, from) => {
if (to.path !== '/search') {
// 将重定向代码设置为 '301 Moved Permanently'
return navigateTo('/search', { redirectCode: 301 })
}
})
在路由中间件中使用 navigateTo 时，必须返回其结果，以确保中间件的执行流程正常工作。
例如，以下实现不会按预期工作：
export default defineNuxtRouteMiddleware((to, from) => {
if (to.path !== '/search') {
// ❌ 这不会按预期工作
navigateTo('/search', { redirectCode: 301 })
return
}
})
在这种情况下，navigateTo 会被执行但不会被返回，这可能导致意外行为。
导航到外部 URL
navigateTo 中的 external 参数会影响 URL 导航的处理方式：
- 不使用
external: true时：- 内部 URL 按预期导航。
- 外部 URL 会抛出错误。
- 使用
external: true时：- 内部 URL 会通过整页刷新进行导航。
- 外部 URL 按预期导航。
示例
<script setup lang="ts">
// 会抛出错误；
// 默认情况下不允许导航到外部 URL
await navigateTo('https://nuxt.com')
// 将 'external' 参数设为 'true' 后会成功重定向
await navigateTo('https://nuxt.com', {
external: true
})
</script>
在新标签页中打开页面
<script setup lang="ts">
// 会在新标签页中打开 'https://nuxt.com'
await navigateTo('https://nuxt.com', {
open: {
target: '_blank',
windowFeatures: {
width: 500,
height: 500
}
}
})
</script>
类型
function navigateTo(
to: RouteLocationRaw | undefined | null,
options?: NavigateToOptions
) => Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw
interface NavigateToOptions {
replace?: boolean
redirectCode?: number
external?: boolean
open?: OpenOptions
}
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 }>
参数
to
类型： RouteLocationRaw | undefined | null
默认值： '/'
to 可以是一个纯字符串或一个要重定向到的路由对象。当传递 undefined 或 null 时，它将默认为 '/'。
示例
// 直接传递 URL 将重定向到 '/blog' 页面
await navigateTo('/blog')
// 使用路由对象，将重定向到名称为 'blog' 的路由
await navigateTo({ name: 'blog' })
// 使用路由对象重定向到 'product' 路由并传递参数（id = 1）
await navigateTo({ name: 'product', params: { id: 1 } })
options（可选）
类型： NavigateToOptions
一个接受以下属性的对象：
replace- 类型：
boolean - 默认值：
false - 默认情况下，
navigateTo在客户端会将给定的路由推入 Vue Router 实例。
可以通过将replace设置为true来更改此行为，表示应替换给定的路由。
- 类型：
redirectCode- 类型：
number - 默认值：
302 - 当在服务器端进行重定向时，
navigateTo会重定向到给定的路径，并默认将重定向代码设置为302 Found。
可以通过提供不同的redirectCode来修改此默认行为。通常，301 Moved Permanently可用于永久重定向。
- 类型：
external- 类型：
boolean - 默认值：
false - 设为
true时允许导航到外部 URL。否则，navigateTo会抛出错误，因为默认情况下不允许外部导航。
- 类型：
open- 类型：
OpenOptions - 允许使用窗口的 open() 方法导航到 URL。此选项仅适用于客户端，在服务器端会被忽略。
一个接受以下属性的对象： target- 类型：
string - 默认值：
'_blank' - 一个不含空格的字符串，指定资源加载到的浏览上下文的名称。
- 类型：
windowFeatures- 类型：
OpenWindowFeatures - 一个接受以下属性的对象：
| 属性 | 类型 | 描述 | |----------|---------|--------------| |popup|boolean| 请求一个最小化的弹出窗口而不是新标签页，UI 功能由浏览器决定。 | |width或innerWidth|number| 指定内容区域的宽度（最小 100 像素），包括滚动条。 | |height或innerHeight|number| 指定内容区域的高度（最小 100 像素），包括滚动条。 | |left或screenX|number| 设置新窗口相对于屏幕左边缘的水平位置。 | |top或screenY|number| 设置新窗口相对于屏幕上边缘的垂直位置。 | |noopener|boolean| 阻止新窗口通过window.opener访问原始窗口。 | |noreferrer|boolean| 阻止发送 Referer 标头，并隐式启用noopener。 |
有关 windowFeatures 属性的更多详细信息，请参阅 文档。
- 类型：
- 类型：