Uso

navigateTo está disponível tanto no lado do servidor quanto no lado do cliente. Pode ser usado dentro do contexto do Nuxt, ou diretamente, para realizar a navegação de página.

Dentro de um Componente Vue

// passando 'to' como uma string
await navigateTo('/search')

// ... ou como um objeto de rota
await navigateTo({ path: '/search' })

// ... ou como um objeto de rota com parâmetros de consulta
await navigateTo({
  path: '/search',
  query: {
    page: 1,
    sort: 'asc'
  }
})

Dentro de Middleware de Rota

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // definindo o código de redirecionamento para '301 Moved Permanently'
    return navigateTo('/search', { redirectCode: 301 })
  }
})

Ao usar navigateTo dentro de middleware de rota, você deve retornar seu resultado para garantir que o fluxo de execução do middleware funcione corretamente.

Por exemplo, a seguinte implementação não funcionará como esperado:

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // ❌ Isso não funcionará como esperado
    navigateTo('/search', { redirectCode: 301 })
    return
  }
})

Neste caso, navigateTo será executado, mas não retornado, o que pode levar a um comportamento inesperado.

Navegando para uma URL Externa

O parâmetro external em navigateTo influencia como a navegação para URLs é tratada:

• Sem external: true:

  • URLs internas navegam como esperado.
  • URLs externas lançam um erro.

• Com external: true:

  • URLs internas navegam com um recarregamento completo da página.
  • URLs externas navegam como esperado.

Exemplo

// lançará um erro;
// navegar para uma URL externa não é permitido por padrão
await navigateTo('https://nuxt.com')

// redirecionará com sucesso com o parâmetro 'external' definido como 'true'
await navigateTo('https://nuxt.com', {
  external: true
})

Abrindo uma Página em uma Nova Aba

// abrirá 'https://nuxt.com' em uma nova aba
await navigateTo('https://nuxt.com', {
  open: {
    target: '_blank',
    windowFeatures: {
      width: 500,
      height: 500
    }
  }
})

Tipo

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

Parâmetros

to

Tipo: RouteLocationRaw | undefined | null

Padrão: '/'

to pode ser uma string simples ou um objeto de rota para redirecionar. Quando passado como undefined ou null, será padrão para '/'.

Exemplo

// Passando a URL diretamente redirecionará para a página '/blog'
await navigateTo('/blog')

// Usando o objeto de rota, redirecionará para a rota com o nome 'blog'
await navigateTo({ name: 'blog' })

// Redireciona para a rota 'product' enquanto passa um parâmetro (id = 1) usando o objeto de rota.
await navigateTo({ name: 'product', params: { id: 1 } })

options (opcional)

Tipo: NavigateToOptions

Um objeto que aceita as seguintes propriedades:

• replace

  • Tipo: boolean

  • Padrão: false

  • Por padrão, navigateTo empurra a rota dada na instância do Vue Router no lado do cliente.

    Esse comportamento pode ser alterado definindo replace como true, para indicar que a rota dada deve ser substituída.

• redirectCode

  • Tipo: number

  • Padrão: 302

  • navigateTo redireciona para o caminho dado e define o código de redirecionamento para 302 Found por padrão quando o redirecionamento ocorre no lado do servidor.

    Esse comportamento padrão pode ser modificado fornecendo um redirectCode diferente. Comumente, 301 Moved Permanently pode ser usado para redirecionamentos permanentes.

• external

  • Tipo: boolean

  • Padrão: false

  • Permite navegar para uma URL externa quando definido como true. Caso contrário, navigateTo lançará um erro, pois a navegação externa não é permitida por padrão.

• open

  • Tipo: OpenOptions

  • Permite navegar para a URL usando o método open() da janela. Esta opção é aplicável apenas no lado do cliente e será ignorada no lado do servidor.

    Um objeto que aceita as seguintes propriedades:

  • target

    • Tipo: string

    • Padrão: '_blank'

    • Uma string, sem espaços em branco, especificando o nome do contexto de navegação em que o recurso está sendo carregado.

  • windowFeatures

    • Tipo: OpenWindowFeatures

    • Um objeto que aceita as seguintes propriedades:

      Propriedade	Tipo	Descrição
      popup	boolean	Solicita uma janela popup mínima em vez de uma nova aba, com recursos de UI decididos pelo navegador.
      width ou innerWidth	number	Especifica a largura da área de conteúdo (mínimo 100 pixels), incluindo barras de rolagem.
      height ou innerHeight	number	Especifica a altura da área de conteúdo (mínimo 100 pixels), incluindo barras de rolagem.
      left ou screenX	number	Define a posição horizontal da nova janela em relação à borda esquerda da tela.
      top ou screenY	number	Define a posição vertical da nova janela em relação à borda superior da tela.
      noopener	boolean	Impede que a nova janela acesse a janela de origem via window.opener.
      noreferrer	boolean	Impede que o cabeçalho Referer seja enviado e implicitamente habilita noopener.

      Consulte a documentação para informações mais detalhadas sobre as propriedades windowFeatures.