<Link>

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

基本用法

pages/index.tsx

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

参考

以下 props 可以传递给 <Link> 组件

Prop	示例	类型	必需
`href`	`href="/dashboard"`	字符串或对象	是
`replace`	`replace={false}`	布尔值	-
`scroll`	`scroll={false}`	布尔值	-
`prefetch`	`prefetch={false}`	布尔值	-
`legacyBehavior`	`legacyBehavior={true}`	布尔值	-
`passHref`	`passHref={true}`	布尔值	-
`shallow`	`shallow={false}`	布尔值	-
`locale`	`locale="fr"`	字符串或布尔值	-

**注意**：<a> 标签属性（例如 className 或 target="_blank"）可以作为 props 添加到 <Link> 中，并将传递到底层的 <a> 元素。

`href`（必需）

要导航到的路径或 URL。

pages/index.tsx

import Link from 'next/link'
 
// Navigate to /about?name=test
export default function Home() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

`replace`

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

pages/index.tsx

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

`scroll`

**默认为 true。**Next.js 中 <Link> 的默认滚动行为**是保持滚动位置**，类似于浏览器处理前进和后退导航的方式。当您导航到新的页面时，只要页面在视口中可见，滚动位置就会保持不变。但是，如果页面在视口中不可见，Next.js 将滚动到第一个页面元素的顶部。

当 scroll = {false} 时，Next.js 不会尝试滚动到第一个页面元素。

pages/index.tsx

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

`prefetch`

当 <Link /> 组件进入用户的视口（最初或通过滚动）时，就会发生预取。Next.js 在后台预取并加载链接的路由（由 href 表示）和数据，以提高客户端导航的性能。**预取仅在生产环境中启用**。

以下值可以传递给prefetch 属性

true（默认）：将预取完整的路由及其数据。
false：进入视口时不会发生预取，但会在悬停时发生。如果您还希望完全移除悬停时的获取，请考虑使用<a>标签或逐步采用App Router，它也支持禁用悬停时的预取。

pages/index.tsx

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

`legacyBehavior`

<Link> 的子元素不再需要 <a> 元素。添加 legacyBehavior 属性以使用旧版行为，或删除 <a> 以进行升级。可以使用代码修改工具自动升级您的代码。

注意：当 legacyBehavior 未设置为 true 时，所有anchor标签属性也可以传递给next/link，例如className、onClick等。

`passHref`

强制Link将其href属性发送到其子元素。默认为false。有关更多信息，请参阅传递函数组件示例。

`scroll`

导航后滚动到页面顶部。默认为true。

pages/index.tsx

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

`shallow`

更新当前页面的路径，无需重新运行getStaticProps、getServerSideProps或getInitialProps。默认为false。

pages/index.tsx

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

`locale`

活动区域设置会自动前置。locale 允许提供不同的区域设置。当 false 时，href 必须包含区域设置，因为默认行为被禁用。

pages/index.tsx

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* Default behavior: locale is prepended */}
      <Link href="/dashboard">Dashboard (with locale)</Link>
 
      {/* Disable locale prepending */}
      <Link href="/dashboard" locale={false}>
        Dashboard (without locale)
      </Link>
 
      {/* Specify a different locale */}
      <Link href="/dashboard" locale="fr">
        Dashboard (French)
      </Link>
    </>
  )
}

示例

以下示例演示了如何在不同场景中使用<Link>组件。

链接到动态路由段

对于动态路由段，使用模板字面量来创建链接的路径会很方便。

例如，您可以生成指向动态路由pages/blog/[slug].js的一系列链接。

pages/blog/index.tsx

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

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

如果Link的子元素是包装了<a>标签的自定义组件，则必须将passHref添加到Link。如果您使用的是像styled-components这样的库，则需要这样做。否则，<a>标签将没有href属性，这会影响网站的可访问性，并可能影响SEO。如果您使用的是ESLint，则内置了一个规则next/link-passhref来确保正确使用passHref。

components/nav-link.tsx

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

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

嵌套函数组件

如果Link的子元素是函数组件，除了使用passHref和legacyBehavior之外，还必须将该组件包装在React.forwardRef中。

pages/index.tsx

import Link from 'next/link'
import React from 'react'
 
// Define the props type for MyButton
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}
 
// Use React.ForwardRefRenderFunction to properly type the forwarded ref
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}
 
// Use React.forwardRef to wrap the component
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

传递URL对象

Link也可以接收URL对象，它会自动将其格式化以创建URL字符串。

pages/index.ts

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

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

替换URL而不是推送

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

pages/index.js

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

禁用滚动到页面顶部

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

pages/index.tsx

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}

在中间件中预取链接

通常使用中间件进行身份验证或其他涉及将用户重写到不同页面的操作。为了使<Link />组件能够通过中间件正确地预取带有重写的链接，您需要告诉Next.js要显示的URL和要预取的URL。这是为了避免不必要的中间件获取以了解要预取的正确路由。

例如，如果您想服务一个具有经过身份验证的用户视图和访客视图的/dashboard路由，您可以在中间件中添加以下内容以将用户重定向到正确的页面。

middleware.ts

import { NextResponse } from 'next/server'
 
export function middleware(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

middleware.js

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

在这种情况下，您需要在您的<Link />组件中使用以下代码

pages/index.tsx

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

了解一下：如果您正在使用动态路由，则需要调整您的as和href属性。例如，如果您有一个像/dashboard/authed/[user]这样的动态路由，您希望通过中间件以不同的方式呈现它，则可以这样写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

版本历史

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