navigateTo

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

Maschinelle Übersetzung ·0 % geprüft

用法

navigateTo 可在服务器端和客户端使用。它可以在 Nuxt 上下文中使用，也可以直接使用，以执行页面导航。

在调用 navigateTo 时，请确保始终对其结果使用 await 或 return。
navigateTo 不能在 Nitro 路由中使用。要在 Nitro 路由中执行服务器端重定向，请改用 sendRedirect。

在 Vue 组件内

<script setup lang="ts">
// 'to' als String übergeben
await navigateTo('/search')

// ... oder als Routen-Objekt
await navigateTo({ path: '/search' })

// ... oder als Routen-Objekt mit Query-Parametern
await navigateTo({
  path: '/search',
  query: {
    page: 1,
    sort: 'asc',
  },
})
</script>
调用 navigateTo 不会停止执行 <script setup> 中的其余代码。如果你希望成功导航后提前从 setup() 返回，请启用 experimental.navigateToEarlyReturn。

在路由中间件中

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // Weiterleitungscode auf '301 Moved Permanently' setzen
    return navigateTo('/search', { redirectCode: 301 })
  }
})

在路由中间件中使用 navigateTo 时，你必须 返回其结果，以确保中间件执行流程正常工作。

例如，以下实现 将无法按预期工作：

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // ❌ Das funktioniert nicht wie erwartet
    navigateTo('/search', { redirectCode: 301 })
    return
  }
})

在这种情况下，navigateTo 会被执行但不会被返回，这可能导致意外行为。

Weitere Informationen findest du unter Docs > Directory Structure > App > Middleware.

导航到外部 URL

navigateTo 中的 external 参数会影响如何处理 URL 导航：

  • 未设置 external: true 时：

    • 内部 URL 会按预期导航。
    • 外部 URL 会抛出错误。

  • 设置 external: true 时：

    • 内部 URL 会以完整页面重新加载的方式导航。
    • 外部 URL 会按预期导航。

示例

<script setup lang="ts">
// will throw an error;
// Die Navigation zu einer externen URL ist standardmäßig nicht erlaubt
await navigateTo('https://nuxt.com')

// leitet erfolgreich weiter, wenn der Parameter 'external' auf 'true' gesetzt ist
await navigateTo('https://nuxt.com', {
  external: true,
})
</script>

在新标签页打开页面

<script setup lang="ts">
// öffnet 'https://nuxt.com' in einer neuen Registerkarte
await navigateTo('https://nuxt.com', {
  open: {
    target: '_blank',
    windowFeatures: {
      width: 500,
      height: 500,
    },
  },
})
</script>

类型

Signatur
export function navigateTo (
  to: RouteLocationRaw | undefined | null,
  options?: NavigateToOptions,
): Promise<void | NavigationFailure | false> | false | void

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 时，默认会使用 '/'。

示例

// Wird die URL direkt übergeben, erfolgt eine Weiterleitung zur Seite '/blog'
await navigateTo('/blog')

// Mit dem Route-Objekt erfolgt eine Weiterleitung zur Route mit dem Namen 'blog'
await navigateTo({ name: 'blog' })

// Redirects to the 'product' route while passing a parameter (id = 1) using the route object.
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

      • 一个接受以下属性的对象：

        属性类型描述
        popupboolean请求一个最小化的弹出窗口而不是新标签页，窗口的 UI 特性由浏览器决定。
        width 或 innerWidthnumber指定内容区域的宽度（最小 100 像素），包括滚动条。
        height 或 innerHeightnumber指定内容区域的高度（最小 100 像素），包括滚动条。
        left 或 screenXnumber设置新窗口相对于屏幕左边缘的水平位置。
        top 或 screenYnumber设置新窗口相对于屏幕顶部的垂直位置。
        noopenerboolean防止新窗口通过 window.opener 访问来源窗口。
        noreferrerboolean阻止发送 Referer 头部，并隐式启用 noopener。

        有关 windowFeatures 属性的更详细信息，请参阅文档。