链接

<Link> 是一个 React 组件，它扩展了 HTML <a> 元素，提供了 预取 和客户端路由之间的导航。这是 Next.js 中在不同路由之间导航的主要方式。

属性

以下是 Link 组件可用属性的摘要：

须知：可以作为属性添加到 <Link> 的 <a> 标签属性，如 className 或 target="_blank"，并将被传递给底层的 <a> 元素。

href (必需)

要导航到的路径或 URL。

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

href 也可以接受一个对象，例如：

// 导航到 /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  关于
</Link>

replace

默认值为 false。 当设置为 true 时，next/link 将替换当前的历史状态，而不是在 浏览器的历史 堆栈中添加一个新的 URL。

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </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>
  )
}

import Link from 'next/link'

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

须知：

• Next.js 将在导航时滚动到 页面，如果它在视口中不可见。

prefetch

示例

链接到动态路由

对于动态路由，使用模板文字来创建链接的路径可能会很有帮助。

如果子元素是一个包装了 <a> 标签的自定义组件

import Link from 'next/link'
import styled from 'styled-components'

// 这创建了一个包装了 <a> 标签的自定义组件
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

• 如果你正在使用 emotion 的 JSX pragma 特性 (@jsx jsx)，即使你直接使用 <a> 标签，也必须使用 passHref。
• 组件应该支持 onClick 属性以正确触发导航

如果子组件是函数组件

如果 Link 的子组件是函数组件，除了使用 passHref 和 legacyBehavior，您还必须使用 React.forwardRef 包装该组件：

import Link from 'next/link'

// `onClick`、`href` 和 `ref` 需要传递给 DOM 元素
// 以正确处理
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      点击我
    </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' },
          }}
        >
          关于我们
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          博客文章
        </Link>
      </li>
    </ul>
  )
}

export default Home

上述示例包含以下链接：

• 一个预定义的路由：/about?name=test
• 一个动态路由：/blog/my-post

您可以使用 Node.js URL 模块文档中定义的每个属性。

替换 URL 而不是推送

Link 组件的默认行为是将一个新的 URL push 到 history 栈中。您可以使用 replace 属性来防止添加新的条目，如下所示：

<Link href="/about" replace>
  关于我们
</Link>

禁用滚动到页面顶部

Link 的默认行为是滚动到页面顶部。当定义了哈希时，它将滚动到特定的 id，就像普通的 <a> 标签一样。为了防止滚动到顶部 / 哈希，可以添加 scroll={false} 到 Link：

<Link href="/#hashid" scroll={false}>
  禁用滚动到顶部
</Link>

Middleware

在使用 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>
  )
}

版本历史

版本	变化
v13.0.0	不再需要子 <a> 标签。提供了一个 codemod 来自动更新你的代码库。
v10.0.0	指向动态路由的 href 属性会自动解析，不再需要 as 属性。
v8.0.0	提高了预取性能。
v1.0.0	引入了 next/link。