navigateTo
navigateTo 是一個輔助函式，用於以程式化方式導航使用者。
用法
navigateTo 在伺服器端和用戶端都可用。它可以在 Nuxt context 內或直接使用，以執行頁面導航。
當呼叫
navigateTo 時，請務必始終在 await 或 return 結果上使用。navigateTo 無法在 Nitro 路由內使用。若要在 Nitro 路由中執行伺服器端重新導向，請改用 sendRedirect。在 Vue 元件內
<script setup lang="ts">
// passing 'to' as a string
await navigateTo('/search')
// ... or as a route object
await navigateTo({ path: '/search' })
// ... or as a route object with query parameters
await navigateTo({
path: '/search',
query: {
page: 1,
sort: 'asc'
}
})
</script>
在路由中介層內
export default defineNuxtRouteMiddleware((to, from) => {
if (to.path !== '/search') {
// setting the redirect code to '301 Moved Permanently'
return navigateTo('/search', { redirectCode: 301 })
}
})
當在路由中介層內使用 navigateTo 時，您必須傳回其結果，以確保中介層執行流程正常運作。
例如，以下實作將無法如預期運作
export default defineNuxtRouteMiddleware((to, from) => {
if (to.path !== '/search') {
// ❌ This will not work as expected
navigateTo('/search', { redirectCode: 301 })
return
}
})
在此情況下，navigateTo 將會執行，但不會傳回，這可能會導致非預期的行為。
導航至外部 URL
navigateTo 中的 external 參數會影響 URL 導航的處理方式
- 沒有
external: true:- 內部 URL 會如預期導航。
- 外部 URL 會拋出錯誤。
- 有
external: true:- 內部 URL 會以完整頁面重新載入的方式導航。
- 外部 URL 會如預期導航。
範例
<script setup lang="ts">
// will throw an error;
// navigating to an external URL is not allowed by default
await navigateTo('https://nuxt.dev.org.tw')
// will redirect successfully with the 'external' parameter set to 'true'
await navigateTo('https://nuxt.dev.org.tw', {
external: true
})
</script>
在新分頁中開啟頁面
<script setup lang="ts">
// will open 'https://nuxt.dev.org.tw' in a new tab
await navigateTo('https://nuxt.dev.org.tw', {
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 傳遞時，它會預設為 '/'。
範例
// Passing the URL directly will redirect to the '/blog' page
await navigateTo('/blog')
// Using the route object, will redirect to the route with the name '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 屬性的更詳細資訊。
- 類型：
- 類型：