<NuxtLink>

Source
Компонент <NuxtLink> для ссылок и навигации в приложении.
<NuxtLink> заменяет и <RouterLink> Vue Router, и HTML-тег <a>. Он определяет, ссылка внутренняя или внешняя, и рендерит её с учётом оптимизаций (префетч, атрибуты по умолчанию и т.д.).

Внутренняя навигация

В примере ниже <NuxtLink> ведёт на другую страницу приложения.

<template>
  <NuxtLink to="/about">О нас</NuxtLink>
</template>

Параметры в динамических маршрутах

В примере параметр id передаётся в маршрут ~/pages/posts/[id].vue.

<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>
В Nuxt DevTools на панели Pages можно посмотреть имя маршрута и его параметры.
При передаче объекта в проп to компонент <NuxtLink> использует обработку query-параметров Vue Router. Ключи и значения кодируются автоматически, вручную вызывать encodeURI или encodeURIComponent не нужно.

Ссылки на статику и другие приложения

По умолчанию <NuxtLink> использует клиентскую навигацию Vue Router для относительных путей. Ссылки на файлы в /public или на другое приложение на том же домене могут давать 404. Используйте проп external, чтобы обойти внутреннюю маршрутизацию Vue Router.

Проп external помечает ссылку как внешнюю. <NuxtLink> рендерит обычный тег <a>.

Ссылки на статические файлы

Для файлов в /public (PDF, изображения) используйте проп external.

app/pages/index.vue
<template>
  <NuxtLink
    to="/example-report.pdf"
    external
  >
    Download Report
  </NuxtLink>
</template>

Ссылка на другое приложение

When pointing to a different application on the same domain, using the external prop ensures the correct behavior.

app/pages/index.vue
<template>
  <NuxtLink
    to="/another-app"
    external
  >
    Go to Another App
  </NuxtLink>
</template>

Проп external или автоматическое определение типа ссылки обеспечивают корректную навигацию и совместимость со статикой и переходами между приложениями.

Внешние ссылки

Пример ссылки на внешний сайт:

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

Атрибуты rel и noRel

По умолчанию к ссылкам с target или к абсолютным URL (http://, https://, //) добавляется rel="noopener noreferrer".

  • noopener устраняет уязвимость в старых браузерах.
  • noreferrer не отправляет заголовок Referer на целевой сайт.

На SEO это не сказывается негативно и считается рекомендуемой практикой.

Переопределить поведение можно пропами rel или noRel.

app/app.vue
<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"
  >About page</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

Проп noRel отключает добавление rel по умолчанию к абсолютным ссылкам.

app/app.vue
<template>
  <NuxtLink
    to="https://github.com/nuxt"
    no-rel
  >
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>
noRel и rel вместе не используются; rel будет проигнорирован.

Prefetch ссылок

Nuxt по умолчанию подгружает (prefetch) JS страниц для ссылок, попадающих в viewport при прокрутке, чтобы переход был быстрее. Загрузка идёт, когда браузер не занят; при offline или 2G prefetch не выполняется.

app/pages/index.vue
<NuxtLink to="/about" no-prefetch>
  Страница без prefetch
</NuxtLink>

<NuxtLink to="/about" :prefetch="false">
  Страница без prefetch
</NuxtLink>

Условия prefetch

Начиная с v3.13.0 поддерживаются свои условия срабатывания prefetch через проп prefetchOn.

<template>
  <NuxtLink prefetch-on="visibility">
    Prefetch при появлении в viewport (по умолчанию)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    Prefetch при наведении или фокусе
  </NuxtLink>
</template>
  • visibility: prefetch при появлении ссылки в viewport (Intersection Observer API).
  • interaction: prefetch при наведении или фокусе (pointerenter, focus).

Можно передать объект с настройками:

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    Prefetch при наведении или фокусе
  </NuxtLink>
</template>

Включение обоих триггеров может привести к лишним загрузкам:

<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    Prefetch при наведении/фокусе или при появлении в viewport
  </NuxtLink>
</template>

Один и тот же ресурс может подгрузиться дважды — по разным условиям.

Cross-origin prefetch

Включение в nuxt.config: опция crossOriginPrefetch. Используется Speculation Rules API.

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

Отключить prefetch глобально

Можно отключить или включить prefetch для всех ссылок приложения.

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

Пропсы

RouterLink

Без external поддерживаются все пропсы RouterLink Vue Router:

  • to: URL или объект локации маршрута
  • custom: не оборачивать контент в <a>, полный контроль над рендером и навигацией. Как custom у Vue Router
  • exactActiveClass: класс для точного совпадения маршрута (по умолчанию "router-link-exact-active")
  • activeClass: класс для активной ссылки (по умолчанию "router-link-active")
  • replace: как replace у Vue Router
  • ariaCurrentValue: значение aria-current для точного совпадения

NuxtLink

  • href: синоним to; при наличии to игнорируется
  • noRel: не добавлять rel к внешним ссылкам
  • external: рендерить как <a>, а не RouterLink
  • prefetch: включённый prefetch подгружает middleware, макеты и payload (при payloadExtraction) для ссылок в viewport
  • prefetchOn: когда prefetch — interaction или visibility (по умолчанию); можно объект { interaction: true, visibility: true }. Учитывается при включённом prefetch и без noPrefetch
  • noPrefetch: отключить prefetch
  • prefetchedClass: класс для уже подгруженных ссылок

Anchor

  • target: атрибут target
  • rel: атрибут rel (для внешних по умолчанию "noopener noreferrer")
Значения по умолчанию можно переопределить — см. переопределение.

Переопределение значений по умолчанию

В nuxt.config

Часть значений по умолчанию для <NuxtLink> задаётся в nuxt.config.

В будущем эти опции могут быть перенесены в app.config или в app/.
nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // значения по умолчанию
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // can be any valid string class name
        trailingSlash: undefined, // can be 'append' or 'remove'
        prefetch: true,
        prefetchOn: { visibility: true },
      },
    },
  },
})

Custom Link Component

Переопределить значения по умолчанию можно, создав свой компонент ссылки через defineNuxtLink.

app/components/MyNuxtLink.ts
export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* см. сигнатуру ниже */
})

Компонент <MyNuxtLink /> затем можно использовать как обычно с новыми значениями по умолчанию.

defineNuxtLink Signature

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: имя компонента. По умолчанию NuxtLink.
  • externalRelAttribute: значение атрибута rel для внешних ссылок. По умолчанию "noopener noreferrer". Пустая строка "" отключает.
  • activeClass: класс для активной ссылки. Аналог Vue Router linkActiveClass. По умолчанию "router-link-active".
  • exactActiveClass: класс для точного совпадения. Аналог Vue Router linkExactActiveClass. По умолчанию "router-link-exact-active".
  • trailingSlash: добавлять или убирать завершающий слэш в href. Допустимы append или remove, иначе игнорируется.
  • prefetch: префетчить ссылки по умолчанию или нет.
  • prefetchOn: детальная настройка стратегий префетча по умолчанию.
  • prefetchedClass: класс для ссылок, которые уже префетчены.
Прочитайте и отредактируйте живой пример в Docs > 4 X > Examples > Routing > Pages.