[번역] next/link 공식 문서

2020년 12월에 번역된 글로 현재와 다른 내용이 있을 수 있습니다.

 

다음은 nextjs 공식문서의 nextjs api 레퍼런스 중 next/link에 대한 글을 번역한 것이다.

nextjs.org/docs/api-reference/next/link

next/link | Next.js

next/link

예제 앱

• Hello World
• Active className on Link

읽기 전에, Routing Introduction을 읽어볼 것을 권한다.

 

클라이언트 사이드에서 경로간의 이동은 Link 컴포넌트(exported by next/link)를 통해 활성화될 수 있다. 

예를 들어, pages 디렉토리가 아래와 같은 파일로 구성되어 있다고 생각해보자:

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

우리는 각 페이지로의 링크를 아래처럼 사용할 수 있다:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">
          <a>Home</a>
        </Link>
      </li>
      <li>
        <Link href="/about">
          <a>About Us</a>
        </Link>
      </li>
      <li>
        <Link href="/blog/hello-world">
          <a>Blog Post</a>
        </Link>
      </li>
    </ul>
  )
}

export default Home

Link 는 다음과 같은 props를 허용한다:

• href - 이동할 경로 혹은 URL. 유일한 필수 prop. (필수이기 때문에 href를 안 적으면 에러난다)
• as - 브라우저 URL 표시 줄에 표시 될 경로에 대한 선택적 데코레이터. Next.js 9.5.3 이전에는 동적 경로에 사용되었으므로 이전 문서 에서 작동 방식을 확인하길 바란다.
• passHref - href property를 Link 자식에게 강제로 전달하게 한다. 기본값은 false.
• prefetch - 백그라운드에서 페이지를 미리 가져온다. 기본값은 true. <Link /> 뷰 포트에 있는 모든 항목(초기에 혹은 스크롤을 통해)이 미리 로드 된다. prefetch={false}를 통해 프리페치를 비활성화할 수 있다. 정적 생성을 사용하는 페이지는 더 빠른 페이지 전환을 위해 데이터가 포함된 JSON파일을 미리 로드한다.
• replace - history 스택(방문 기록)에 새 url을 추가하는 대신 현재 상태를 변경한다. 기본값은 false
• scroll - 페이지 전환 후 페이지 상단으로 스크롤할지 여부. 기본값은 true.
• shallow - getStaticProps, getServerSideProps,  getInitialProps을 다시 실행하지 않고 현재 경로를 업데이트. 기본값은 false.

 

경로에 동적 세그먼트가 있는 경우(변하는 부분이 있는 경우)

Next.js 9.5.3 (이전 버전의 경우 이전 문서 확인) 이후로 모든 경로를 캐치하는 것을 포함해 동적 경로에 연결할 때 특별히해야 할 일은 없다. 그러나 보간(interpolation)이나 URL 객체를 사용해 링크를 생성하는 것은 일반적이고 편리한 편이다.

예를 들어, 동적 경로 pages/blog/[slug].js 는 다음 링크와 일치한다:

import Link from 'next/link'

function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${encodeURIComponent(post.slug)}`}>
            <a>{post.title}</a>
          </Link>
        </li>
      ))}
    </ul>
  )
}

export default Posts

 

Link의 자식이 <a> 태그로 감싸진 커스텀 컴포넌트인 경우

Link의 자식이 <a> 태그로 감싸진 커스텀 컴포넌트라면 반드시 passHref를 Link에 추가해야한다. styled-components와 같은 라이브러리를 사용할 때 필수적이다. 이것이 없으면 <a> 태그의 href 속성이 없어 사이트의 SEO가 손상될 수 있다.

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 }) {
  // Must add passHref to Link
  return (
    <Link href={href} passHref>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

참고: 만약 emotion의 JSX pragma 기능(@jsx jsx)을 사용한다면, <a>태그를 직접적으로 사용하더라도 반드시  passHref를 사용해야한다.

자식이 함수형 컴포넌트인 경우

Link의 자식이 함수 컴포넌트인 경우 passHref를 사용하는 것 이외에도 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>
      <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' },
          }}
        >
          <a>About us</a>
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          <a>Blog Post</a>
        </Link>
      </li>
    </ul>
  )
}

export default Home

위의 예는 다음 링크를 가진다:

• 미리 정의된 경로: /about?name=test
• 동적 경로: /blog/my-post

Node.js URL module documentation에 정의된 모든 속성을 사용 가능하다.

 

Push 대신 URL 교체

Link 컴포넌트는 기본적으로 새 URL을 history 스택에 push하도록 동작한다. 다음과 같이 replace prop을 사용해 새 항목을 추가하지 못하도록 할 수 있다:

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

 

페이지 상단으로 스크롤 비활성화

Link는 기본적으로 페이지 최상단으로 스크롤하도록 동작한다. 정의된 해시가 있으면 일반 <a>태그처럼 동작한다. 상단 혹은 해시로의 스크롤을 방지하려면 scroll={false} 을 아래처럼 Link에 추가하면 된다:

<Link href="/?counter=10" scroll={false}>
  <a>Disables scrolling to the top</a>
</Link>