<NuxtLink>

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

Внутренний роутинг

В этом примере мы используем компонент <NuxtLink> для перехода на другую страницу приложения.

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

Передача параметров динамическим маршрутам

В этом примере мы передаем параметр id для ссылки на маршрут ~/pages/posts/[id].vue.

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

Статические файлы и ссылки между приложениями

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

Проп external явно помечает ссылку как внешнюю. <NuxtLink> отрендерит её как обычный HTML-тег <a>, минуя логику Vue Router и указывая напрямую на ресурс.

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

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

pages/index.vue
<template>
  <NuxtLink
    to="/example-report.pdf"
    external
  >
    Скачать отчёт
  </NuxtLink>
</template>

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

При указании на другое приложение на том же домене проп external обеспечивает ожидаемое поведение.

pages/index.vue
<template>
  <NuxtLink
    to="/another-app"
    external
  >
    Другое приложение
  </NuxtLink>
</template>

Использование external или корректная автоматическая обработка даёт предсказуемую навигацию, снижает риск сбоев маршрутизации и улучшает работу со статикой и сценариями «несколько приложений на одном домене».

Внешний роутинг

В этом примере мы используем компонент <NuxtLink> для перехода по ссылке на веб-сайт.

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

Атрибуты rel и noRel

Атрибут rel со значением noopener noreferrer по умолчанию добавляется к ссылкам с атрибутом target и к абсолютным ссылкам (например, начинающимся с http://, https:// или //).

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

Эти значения по умолчанию не оказывают негативного влияния на SEO и считаются лучшей практикой.

Когда вам нужно перезаписать это поведение, вы можете использовать входные параметры rel или noRel.

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

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

  <NuxtLink
    to="/about"
    target="_blank"
  >О нас</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

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

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 будет проигнорирован.

Предзагрузка ссылок

В Nuxt включена умная предзагрузка: по умолчанию определяется видимость ссылки (в области просмотра или при прокрутке), и JavaScript для соответствующих страниц подгружается заранее, чтобы к клику всё было готово. Ресурсы загружаются, когда браузер не перегружен; предзагрузка пропускается при офлайне или соединении уровня 2G.

pages/index.vue
<NuxtLink to="/about" no-prefetch>
О нас (без предзагрузки)
</NuxtLink>

<NuxtLink to="/about" :prefetch="false">
О нас (без предзагрузки)
</NuxtLink>

Пользовательские триггеры предзагрузки

Начиная с v3.13.0 для <NuxtLink> можно задавать триггеры предзагрузки через проп prefetchOn.

<template>
  <NuxtLink prefetch-on="visibility">
    Предзагрузка при появлении в области просмотра (по умолчанию)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    Предзагрузка при наведении или фокусе
  </NuxtLink>
</template>
  • visibility: предзагрузка, когда ссылка попадает в область просмотра. Используется Intersection Observer API; срабатывает при прокрутке элемента в видимую зону.
  • interaction: предзагрузка при наведении или фокусе. Обрабатываются события pointerenter и focus, чтобы заранее подгрузить ресурсы, когда пользователь явно проявляет намерение перейти.

Также можно передать объект в prefetchOn:

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

Обычно не стоит включать оба варианта сразу:

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

Такая конфигурация одновременно отслеживает появление ссылки в области просмотра и слушает pointerenter и focus, что может лишний раз тратить ресурсы: оба триггера могут предзагружать один и тот же ресурс в разных условиях.

Кросс-доменная предзагрузка

Чтобы включить предзагрузку с других источников, задайте в nuxt.config опцию crossOriginPrefetch. Будет использоваться Speculation Rules API.

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

Отключить предзагрузку глобально

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

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

Входные параметры

Параметры, как у RouterLink

Если не используется external, <NuxtLink> поддерживает все входные параметры RouterLink из Vue Router

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

Дополнительные параметры NuxtLink

  • href: Алиас для to. При использовании to, href будет проигнорирован
  • noRel: Если установлено в true, атрибут rel не будет добавлен к внешней ссылке
  • external: Заставляет ссылку рендериться как тег a вместо RouterLink у Vue Router.
  • prefetch: при включении Nuxt предзагружает для ссылок в области просмотра код посредников маршрута и лейаутов; при включённом experimental.payloadExtraction — также данные полезной нагрузки. Кросс-доменная предзагрузка настраивается через experimental.crossOriginPrefetch.
  • prefetchOn: когда предзагружать ссылки — interaction или visibility (по умолчанию). Можно передать объект, например { interaction: true, visibility: true }. Учитывается только при включённой предзагрузке (prefetch по умолчанию) и без noPrefetch.
  • noPrefetch: Отключает предварительную загрузку.
  • prefetchedClass: Класс, применяемый к ссылкам, которые были предварительно загружены.

Якорь

  • target: Значение атрибута target, применяемое к ссылке.
  • rel: Значение атрибута rel, применяемое к ссылке. По умолчанию для внешних ссылок используется "noopener noreferrer".
Значения по умолчанию могут быть перезаписаны, см. раздел перезапись значений по умолчанию, если вы хотите их изменить.

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

В файле nuxt.config

Вы можете перезаписать некоторые значения по умолчанию для <NuxtLink> в вашем nuxt.config

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

Пользовательский компонент ссылки

Вы можете перезаписать значения по умолчанию <NuxtLink>, создав свой собственный компонент ссылок с помощью defineNuxtLink.

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

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

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