사용법

navigateTo는 서버 측과 클라이언트 측 모두에서 사용할 수 있습니다. Nuxt 컨텍스트 내에서 또는 직접 페이지 이동을 수행하는 데 사용할 수 있습니다.

Vue 컴포넌트 내에서

// 'to'를 문자열로 전달
await navigateTo('/search')

// ... 또는 라우트 객체로 전달
await navigateTo({ path: '/search' })

// ... 또는 쿼리 매개변수가 있는 라우트 객체로 전달
await navigateTo({
  path: '/search',
  query: {
    page: 1,
    sort: 'asc'
  }
})

라우트 미들웨어 내에서

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은 예상대로 이동합니다.

예시

// 오류를 발생시킵니다;
// 기본적으로 외부 URL로의 이동은 허용되지 않습니다
await navigateTo('https://nuxt.com')

// 'external' 매개변수를 'true'로 설정하여 성공적으로 리디렉션합니다
await navigateTo('https://nuxt.com', {
  external: true
})

새 탭에서 페이지 열기

// 'https://nuxt.com'을 새 탭에서 엽니다
await navigateTo('https://nuxt.com', {
  open: {
    target: '_blank',
    windowFeatures: {
      width: 500,
      height: 500
    }
  }
})

타입

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' })

// 라우트 객체를 사용하여 매개변수(id = 1)를 전달하면서 'product' 라우트로 리디렉션합니다.
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 속성에 대한 자세한 정보는 문서를 참조하세요.