v3.16
Nuxt on GitHub

navigateTo

源代码
navigateTo 是一个辅助函数，用于以编程方式导航用户。

使用方法

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 会被执行但未返回，可能会导致意外行为。

阅读更多 Docs > Guide > Directory Structure > Middleware.

导航到外部 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 属性的更多详细信息，请参阅 文档。