Roteamento Interno

Neste exemplo, usamos o componente <NuxtLink> para linkar para outra página da aplicação.

<template>
  <NuxtLink to="/about">Página Sobre</NuxtLink>
</template>

Passando Parâmetros para Rotas Dinâmicas

Neste exemplo, passamos o parâmetro id para linkar para a rota ~/pages/posts/[id].vue.

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>

Lidando com Arquivos Estáticos e Links Entre Aplicações

Por padrão, <NuxtLink> usa a navegação do lado do cliente do Vue Router para rotas relativas. Ao linkar para arquivos estáticos no diretório /public ou para outra aplicação hospedada no mesmo domínio, pode resultar em erros 404 inesperados porque eles não fazem parte das rotas do cliente. Nesses casos, você pode usar a prop external com <NuxtLink> para ignorar o mecanismo de roteamento interno do Vue Router.

A prop external indica explicitamente que o link é externo. <NuxtLink> renderizará o link como uma tag <a> HTML padrão. Isso garante que o link se comporte corretamente, ignorando a lógica do Vue Router e apontando diretamente para o recurso.

Linkando para Arquivos Estáticos

Para arquivos estáticos no diretório /public, como PDFs ou imagens, use a prop external para garantir que o link seja resolvido corretamente.

<template>
  <NuxtLink to="/example-report.pdf" external>
    Baixar Relatório
  </NuxtLink>
</template>

Linkando para uma URL de Outra Aplicação

Ao apontar para uma aplicação diferente no mesmo domínio, usar a prop external garante o comportamento correto.

<template>
  <NuxtLink to="/another-app" external>
    Ir para Outra Aplicação
  </NuxtLink>
</template>

Usar a prop external ou confiar no tratamento automático garante a navegação adequada, evita problemas de roteamento inesperados e melhora a compatibilidade com recursos estáticos ou cenários entre aplicações.

Roteamento Externo

Neste exemplo, usamos o componente <NuxtLink> para linkar para um site.

<template>
  <NuxtLink to="https://nuxtjs.org">
    Site do Nuxt
  </NuxtLink>
  <!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>

Atributos rel e noRel

Um atributo rel de noopener noreferrer é aplicado por padrão a links com um atributo target ou a links absolutos (por exemplo, links começando com http://, https://, ou //).

• noopener resolve um bug de segurança em navegadores antigos.
• noreferrer melhora a privacidade dos seus usuários ao não enviar o cabeçalho Referer para o site vinculado.

Esses padrões não têm impacto negativo no SEO e são considerados melhores práticas.

Quando você precisa sobrescrever esse comportamento, pode usar as props rel ou noRel.

<template>
  <NuxtLink to="https://twitter.com/nuxt_js">
    Nuxt Twitter
  </NuxtLink>
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->

  <NuxtLink to="https://discord.nuxtjs.org" rel="noopener">
    Nuxt Discord
  </NuxtLink>
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->

  <NuxtLink to="/about" target="_blank">Página Sobre</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

Uma prop noRel pode ser usada para impedir que o atributo rel padrão seja adicionado aos links absolutos.

<template>
  <NuxtLink to="https://github.com/nuxt" no-rel>
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>

Pré-carregamento de Links

O Nuxt inclui automaticamente o pré-carregamento inteligente. Isso significa que ele detecta quando um link está visível (por padrão), seja na janela de visualização ou ao rolar, e pré-carrega o JavaScript para essas páginas para que estejam prontas quando o usuário clicar no link. O Nuxt só carrega os recursos quando o navegador não está ocupado e pula o pré-carregamento se sua conexão estiver offline ou se você tiver apenas conexão 2g.

<NuxtLink to="/about" no-prefetch>Página Sobre não pré-carregada</NuxtLink>
<NuxtLink to="/about" :prefetch="false">Página Sobre não pré-carregada</NuxtLink>

Gatilhos de Pré-carregamento Personalizados

Agora suportamos gatilhos de pré-carregamento personalizados para <NuxtLink> após v3.13.0. Você pode usar a prop prefetchOn para controlar quando pré-carregar links.

<template>
  <NuxtLink prefetch-on="visibility">
    Isso será pré-carregado quando se tornar visível (padrão)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    Isso será pré-carregado quando passar o mouse ou quando ganhar foco
  </NuxtLink>
</template>

• visibility: Pré-carrega quando o link se torna visível na janela de visualização. Monitora a interseção do elemento com a janela de visualização usando a API Intersection Observer. O pré-carregamento é acionado quando o elemento é rolado para a visualização.
• interaction: Pré-carrega quando o link é passado o mouse ou focado. Essa abordagem escuta eventos pointerenter e focus, pré-carregando proativamente recursos quando o usuário indica intenção de interagir.

Você também pode usar um objeto para configurar prefetchOn:

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    Isso será pré-carregado quando passar o mouse ou quando ganhar foco
  </NuxtLink>
</template>

Provavelmente você não quer ambos habilitados!

<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    Isso será pré-carregado quando passar o mouse/foco - ou quando se tornar visível
  </NuxtLink>
</template>

Esta configuração observará quando o elemento entra na janela de visualização e também escutará eventos pointerenter e focus. Isso pode resultar em uso desnecessário de recursos ou pré-carregamento redundante, já que ambos os gatilhos podem pré-carregar o mesmo recurso em condições diferentes.

Habilitar Pré-carregamento Cross-origin

Para habilitar o pré-carregamento cross-origin, você pode definir a opção crossOriginPrefetch no seu nuxt.config. Isso habilitará o pré-carregamento cross-origin usando a API Speculation Rules.

export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

Desabilitar pré-carregamento globalmente

Também é possível habilitar/desabilitar o pré-carregamento de todos os links globalmente para sua aplicação.

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

Props

RouterLink

Quando não estiver usando external, <NuxtLink> suporta todas as props RouterLink do Vue Router

• to: Qualquer URL ou um objeto de localização de rota do Vue Router
• custom: Se <NuxtLink> deve envolver seu conteúdo em um elemento <a>. Permite ter controle total sobre como um link é renderizado e como a navegação funciona quando é clicado. Funciona da mesma forma que a prop custom do Vue Router
• exactActiveClass: Uma classe para aplicar em links exatamente ativos. Funciona da mesma forma que a prop exactActiveClass do Vue Router em links internos. O padrão é o padrão do Vue Router ("router-link-exact-active")
• activeClass: Uma classe para aplicar em links ativos. Funciona da mesma forma que a prop activeClass do Vue Router em links internos. O padrão é o padrão do Vue Router ("router-link-active")
• replace: Funciona da mesma forma que a prop replace do Vue Router em links internos
• ariaCurrentValue: Um valor de atributo aria-current para aplicar em links exatamente ativos. Funciona da mesma forma que a prop ariaCurrentValue do Vue Router em links internos

NuxtLink

• href: Um alias para to. Se usado com to, href será ignorado
• noRel: Se definido como true, nenhum atributo rel será adicionado ao link externo
• external: Força o link a ser renderizado como uma tag <a> em vez de um RouterLink do Vue Router.
• prefetch: Quando habilitado, pré-carregará middleware, layouts e payloads (ao usar payloadExtraction) de links na janela de visualização. Usado pela configuração experimental crossOriginPrefetch.
• prefetchOn: Permite controle personalizado de quando pré-carregar links. As opções possíveis são interaction e visibility (padrão). Você também pode passar um objeto para controle total, por exemplo: { interaction: true, visibility: true }. Esta prop é usada apenas quando prefetch está habilitado (padrão) e noPrefetch não está definido.
• noPrefetch: Desabilita o pré-carregamento.
• prefetchedClass: Uma classe para aplicar a links que foram pré-carregados.

Anchor

• target: Um valor de atributo target para aplicar no link
• rel: Um valor de atributo rel para aplicar no link. O padrão é "noopener noreferrer" para links externos.

Sobrescrevendo Padrões

No Config do Nuxt

Você pode sobrescrever alguns padrões do <NuxtLink> no seu nuxt.config

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // valores padrão
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // pode ser qualquer nome de classe de string válido
        trailingSlash: undefined // pode ser 'append' ou 'remove'
        prefetch: true,
        prefetchOn: { visibility: true } 
      }
    }
  }
})

Componente de Link Personalizado

Você pode sobrescrever os padrões do <NuxtLink> criando seu próprio componente de link usando defineNuxtLink.

export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* veja a assinatura abaixo para mais */
})

Você pode então usar o componente <MyNuxtLink /> como de costume com seus novos padrões.

Assinatura defineNuxtLink

interface NuxtLinkOptions {
  componentName?: string;
  externalRelAttribute?: string;
  activeClass?: string;
  exactActiveClass?: string;
  trailingSlash?: 'append' | 'remove'
  prefetch?: boolean
  prefetchedClass?: string
  prefetchOn?: Partial<{
    visibility: boolean
    interaction: boolean
  }>
}
function defineNuxtLink(options: NuxtLinkOptions): Component {}

• componentName: Um nome para o componente. O padrão é NuxtLink.
• externalRelAttribute: Um valor padrão de atributo rel aplicado em links externos. O padrão é "noopener noreferrer". Defina como "" para desabilitar
• activeClass: Uma classe padrão para aplicar em links ativos. Funciona da mesma forma que a opção linkActiveClass do Vue Router. O padrão é o padrão do Vue Router ("router-link-active")
• exactActiveClass: Uma classe padrão para aplicar em links exatamente ativos. Funciona da mesma forma que a opção linkExactActiveClass do Vue Router. O padrão é o padrão do Vue Router ("router-link-exact-active")
• trailingSlash: Uma opção para adicionar ou remover barras finais no href. Se não definido ou não corresponder aos valores válidos append ou remove, será ignorado.
• prefetch: Se deve ou não pré-carregar links por padrão.
• prefetchOn: Controle granular de quais estratégias de pré-carregamento aplicar por padrão.
• prefetchedClass: Uma classe padrão para aplicar a links que foram pré-carregados.