<Link>

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

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

Свойства

Вот краткое описание свойств, доступных для компонента 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 заменит текущее состояние истории вместо добавления нового URL в стек истории браузера.

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) и его данные в фоновом режиме, чтобы улучшить производительность навигации на стороне клиента. Предварительная загрузка включена только в производстве.

• null (по умолчанию): Поведение предварительной загрузки зависит от того, статический или динамический маршрут. Для статических маршрутов будет предварительно загружен весь маршрут (включая все данные). Для динамических маршрутов будет предварительно загружен частичный маршрут до ближайшего сегмента с границей loading.js.
• true: Полный маршрут будет предварительно загружен для статических и динамических маршрутов.
• false: Предварительная загрузка никогда не происходит как при входе в область просмотра, так и при наведении курсора.

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

Примеры

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

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

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

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

Если дочерний элемент — это пользовательский компонент, который оборачивает тег <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

• Если вы используете функцию pragma 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>

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

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

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

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

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