<Link>

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

基本用法：

pages/index.tsx

TypeScript

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

参考

<Link> 组件可以接收以下属性：

属性	示例	类型	必需
`href`	`href="/dashboard"`	String 或 Object	是
`replace`	`replace={false}`	Boolean	-
`scroll`	`scroll={false}`	Boolean	-
`prefetch`	`prefetch={false}`	Boolean	-
`legacyBehavior`	`legacyBehavior={true}`	Boolean	-
`passHref`	`passHref={true}`	Boolean	-
`shallow`	`shallow={false}`	Boolean	-
`locale`	`locale="fr"`	String 或 Boolean	-

值得注意的是：诸如 className 或 target="_blank" 这样的 <a> 标签属性可以作为属性传递给 <Link>，并会被传递给底层的 <a> 元素。

`href` (必需)

要导航到的路径或 URL。

pages/index.tsx

TypeScript

import Link from 'next/link'
 
// 导航到 /about?name=test
export default function Home() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      关于
    </Link>
  )
}

`replace`

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

pages/index.tsx

TypeScript

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

`scroll`

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

当 scroll = {false} 时，Next.js 将不会尝试滚动到页面元素的顶部。

pages/index.tsx

TypeScript

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

`prefetch`

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

prefetch 属性可以接受以下值：

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

pages/index.tsx

TypeScript

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

`legacyBehavior`

不再需要将 <a> 元素作为 <Link> 的子元素。添加 legacyBehavior 属性可以使用旧的行为，或者移除 <a> 以升级。提供了一个代码转换工具来自动更新你的代码。

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

`passHref`

强制 Link 将 href 属性发送给其子元素。默认为 false。查看传递函数组件示例以了解更多信息。

`scroll`

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

pages/index.tsx

TypeScript

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

`shallow`

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

pages/index.tsx

TypeScript

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

`locale`

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

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* 默认行为：添加 locale 前缀 */}
      <Link href="/dashboard">仪表盘（带 locale）</Link>
 
      {/* 禁用 locale 前缀 */}
      <Link href="/dashboard" locale={false}>
        仪表盘（不带 locale）
      </Link>
 
      {/* 指定不同的 locale */}
      <Link href="/dashboard" locale="fr">
        仪表盘（法语）
      </Link>
    </>
  )
}

示例

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

链接到动态路由段

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

例如，你可以生成一个链接列表指向动态路由 pages/blog/[slug].js：

pages/blog/index.tsx

TypeScript

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

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

components/nav-link.tsx

TypeScript

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 中：

pages/index.tsx

TypeScript

import Link from 'next/link'
import React from 'react'
 
// 为 MyButton 定义属性类型
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}
 
// 使用 React.ForwardRefRenderFunction 为转发的 ref 正确设置类型
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      点击我
    </a>
  )
}
 
// 使用 React.forwardRef 包装组件
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

传递 URL 对象

Link 也可以接收一个 URL 对象，它会自动格式化该对象以创建 URL 字符串：

pages/index.ts

TypeScript

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 而不是 push

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

pages/index.js

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/about" replace>
      关于我们
    </Link>
  )
}

禁用滚动到页面顶部

Link 的默认行为是滚动到页面顶部。当存在 hash 时，它会滚动到特定的 id，就像普通的 <a> 标签一样。要阻止滚动到顶部/hash，可以给 Link 添加 scroll={false}：

pages/index.tsx

TypeScript

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      禁用滚动到顶部
    </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

TypeScript

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的认证钩子
 
export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      仪表盘
    </Link>
  )
}

pages/index.js

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的认证钩子
 
export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      仪表盘
    </Link>
  )
}

值得注意的是：如果你正在使用动态路由，你需要调整你的 as 和 href 属性。例如，如果你有一个动态路由 /dashboard/authed/[user]，你想通过中间件以不同方式呈现它，你应该这样写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">个人资料</Link>。

版本历史

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