<Link>

<Link> это компонент React, который расширяет HTML-элемент <a>, чтобы обеспечить предварительную загрузку и навигацию по страницам на стороне клиента. Это основной способ навигации между страницами в Next.js.

Например, рассмотрим директорию pages с такими файлами:

• pages/index.js
• pages/about.js
• pages/blog/[slug].js

У нас может быть ссылка на каждую из этих страниц следующим образом:

import Link from 'next/link'
 
function Home() {
  return (
    <ul>
      <li>
        <Link href="/">Home</Link>
      </li>
      <li>
        <Link href="/about">About Us</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">Blog Post</Link>
      </li>
    </ul>
  )
}
 
export default Home

Свойства

Вот сводка доступных свойств для компонента Link:

Важно знать: атрибуты тега <a>, такие как className или target="_blank", могут быть добавлены в <Link> как свойства и будут переданы базовому элементу <a>.

href (обязательно)

Путь или URL для перехода.

<Link href="/dashboard">Dashboard</Link>

href также может принимать объект, например:

// Navigate to /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  About
</Link>

replace

По умолчанию false. Когда true, next/link заменит текущее состояние истории вместо добавления новой ссылки в стек истории браузера.

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

scroll

По умолчанию true. По умолчанию <Link> прокручивает страницу к верху после перехода или сохраняет позицию прокрутки при навигации назад и вперед. Когда false, next/link не будет прокручивать страницу до верха после перехода.

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

Важно знать:

• Next.js прокрутит к странице Страница, если она не видна в области просмотра после навигации.

prefetch

Предварительная загрузка происходит, когда компонент <Link /> попадает в область просмотра пользователя (вначале или при прокрутке). Next.js предварительно загружает и загружает связанный маршрут (обозначенный href) и данные в фоновом режиме, чтобы улучшить производительность навигации на стороне клиента. Предварительная загрузка активна только в релизной сборке.

• true (по умолчанию): весь маршрут и его данные будут предварительно загружены.
• false: предварительная загрузка не будет происходить при входе в область просмотра, но будет происходить при наведении. Если вы хотите полностью отключить предварительную загрузку при наведении, рассмотрите использование тега <a> или поэтапную адаптацию App Router, который также позволяет отключить предварительную загрузку при наведении.

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

Другие свойства

legacyBehavior

Элемент <a> больше не требуется в качестве дочернего элемента <Link>. Добавьте свойство legacyBehavior для использования устаревшего поведения или удалите <a> для обновления. Доступен кодмод для автоматического обновления вашего кода.

Важно знать: когда legacyBehavior не установлено в true, все свойства тега anchor также могут быть переданы в next/link, такие как className, onClick, и т.д.

passHref

Принудительно отправляет свойство Link в дочерний элемент. По умолчанию false

scroll

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

shallow

Обновить путь текущей страницы без повторного запуска getStaticProps, getServerSideProps или getInitialProps. По умолчанию false

locale

Активный язык автоматически добавляется в начало. locale позволяет указать другой язык. Когда false href должен включать язык, так как по умолчанию это поведение отключено.

Примеры

Ссылка на динамические маршруты

Для динамических маршрутов полезно использовать шаблонные литералы для создания пути ссылки.

Например, вы можете сгенерировать список ссылок на динамический маршрут pages/blog/[slug].js

import Link from 'next/link'
 
function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}
 
export default Posts

Если дочерний элемент — это пользовательский компонент, обернутый тегом <a>

Если дочерним элементом Link является пользовательский компонент, обернутый тегом <a>, вы должны добавить passHref в Link. Это необходимо, если вы используете такие библиотеки, как styled-components. Без этого тег <a> не будет иметь атрибут href, что ухудшает доступность сайта и может повлиять на SEO. Если вы используете ESLint, существует встроенное правило next/link-passhref для обеспечения правильного использования passHref.

import Link from 'next/link'
import styled from 'styled-components'
 
// This creates a custom component that wraps an <a> tag
const RedLink = styled.a`
  color: red;
`
 
function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}
 
export default NavLink

• Если вы используете функциональность JSX-предиката библиотеки emotion (@jsx jsx), вы должны использовать passHref даже если вы используете тег <a> напрямую.
• Компонент должен поддерживать свойство onClick для правильного запуска навигации.

Если дочерний элемент — функциональный компонент

Если дочерним элементом Link является функциональный компонент, помимо использования passHref и legacyBehavior, вы должны обернуть компонент в React.forwardRef:

import Link from 'next/link'
 
// `onClick`, `href`, and `ref` need to be passed to the DOM element
// for proper handling
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
})
 
function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}
 
export default Home

С объектом URL

Link также может принимать объект URL, и он автоматически отформатирует его для создания строки URL. Вот как это сделать:

import Link from 'next/link'
 
function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          About us
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blog Post
        </Link>
      </li>
    </ul>
  )
}
 
export default Home

В приведенном выше примере ссылка на:

• Предварительно определенный маршрут: /about?name=test
• Динамический маршрут: /blog/my-post

Вы можете использовать все свойства, как определено в документации модуля URL Node.js.

Замена URL вместо добавления

По умолчанию компонент Link добавляет новый URL в стек history. Вы можете использовать свойство replace для предотвращения добавления новой записи, как в следующем примере:

<Link href="/about" replace>
  About us
</Link>

Отключение прокрутки к началу страницы

По умолчанию Link прокручивает страницу к началу. Если определен хэш, прокрутка будет выполнена к соответствующему идентификатору, как у обычного тега <a>. Чтобы предотвратить прокрутку к началу / хэшу, можно добавить scroll={false} в Link.

<Link href="/#hashid" scroll={false}>
  Disables scrolling to the top
</Link>

Средства разработки

Часто для аутентификации или других целей, требующих перенаправления пользователя на другую страницу, используются средства разработки. Чтобы компонент <Link /> правильно предварительно загружал ссылки с переписыванием через средства разработки, необходимо указать как URL для отображения, так и URL для предварительной загрузки. Это необходимо, чтобы избежать ненужных запросов к средствам разработки для определения правильного маршрута предварительной загрузки.

Например, если вы хотите использовать маршрут /dashboard, который имеет аутентифицированные и незарегистрированные представления, можно добавить что-то подобное в ваши средства разработки для перенаправления пользователя на нужную страницу:

export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', req.url))
    }
  }
}

В этом случае вам нужно использовать следующий код в вашем компоненте <Link />.

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'
 
export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Важно знать: Если вы используете Динамические маршруты, вам необходимо адаптировать свои as и href свойства. Например, если у вас есть динамический маршрут, например /dashboard/authed/[user], который вы хотите представить по-другому с помощью middleware, вы напишете: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>.

История версий