Link

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

基本用法：

app/page.tsx

TypeScript

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

参考

以下属性可以传递给 <Link> 组件：

属性	示例	类型	必需
`href`	`href="/dashboard"`	字符串或对象	是
`replace`	`replace={false}`	布尔值	-
`scroll`	`scroll={false}`	布尔值	-
`prefetch`	`prefetch={false}`	布尔值或空值	-

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

`href`（必需）

要导航到的路径或 URL。

app/page.tsx

TypeScript

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

`replace`

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

app/page.tsx

TypeScript

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

`scroll`

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

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

值得注意的是：Next.js 在管理滚动行为之前会检查 scroll: false。如果启用了滚动，它会识别导航的相关 DOM 节点并检查每个顶级元素。所有不可滚动的元素和没有渲染 HTML 的元素都会被绕过，这包括粘性或固定定位的元素，以及使用 getBoundingClientRect 计算的非可见元素。然后 Next.js 继续遍历兄弟元素，直到找到一个在视口中可见的可滚动元素。

app/page.tsx

TypeScript

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

`prefetch`

预加载会在 <Link /> 组件进入用户视口（初始或通过滚动）时发生。Next.js 会在后台预加载和加载链接的路由（由 href 指定）及其数据，以提高客户端导航的性能。如果预加载的数据在用户悬停在 <Link /> 上时已过期，Next.js 将尝试再次预加载。预加载仅在生产环境中启用。

prefetch 属性可传递以下值：

null（默认）：预加载行为取决于路由是静态的还是动态的。对于静态路由，将预加载完整路由（包括所有数据）。对于动态路由，将预加载到最近的带有 loading.js 边界的部分路由。
true：将为静态和动态路由预加载完整路由。
false：在进入视口和悬停时都不会进行预加载。

app/page.tsx

TypeScript

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

示例

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

链接到动态段

在链接到动态段时，你可以使用模板字符串和插值生成链接列表。例如，生成博客文章列表：

app/blog/post-list.tsx

TypeScript

import Link from 'next/link'
 
interface Post {
  id: number
  title: string
  slug: string
}
 
export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

检查活动链接

你可以使用 usePathname() 来确定链接是否处于活动状态。例如，要向活动链接添加类，你可以检查当前的 pathname 是否与链接的 href 匹配：

app/ui/nav-links.tsx

TypeScript

'use client'
 
import { usePathname } from 'next/navigation'
import Link from 'next/link'
 
export function Links() {
  const pathname = usePathname()
 
  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
 
      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

滚动到特定 `id`

如果你想在导航时滚动到特定的 id，可以在 URL 后附加一个带有 # 哈希链接，或者只将哈希链接传递给 href 属性。这是可行的，因为 <Link> 渲染为一个 <a> 元素。

<Link href="/dashboard#settings">Settings</Link>
 
// 输出
<a href="/dashboard#settings">Settings</a>

值得注意的是：

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

链接到动态路由段

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

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

app/blog/page.tsx

TypeScript

import Link from 'next/link'
 
export default function Page({ 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 中：

app/page.tsx

TypeScript

import Link from 'next/link'
import React from 'react'
 
// 为 MyButton 定义 props 类型
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}>
      Click Me
    </a>
  )
}
 
// 使用 React.forwardRef 包装组件
const ForwardedMyButton = React.forwardRef(MyButton)
 
export default function Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

替换 URL 而不是 push

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

app/page.js

TypeScript

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

禁止滚动到页面顶部

Next.js 中 <Link> 的默认滚动行为是保持滚动位置，类似于浏览器处理前进和后退导航的方式。当你导航到新的页面时，只要页面在视口中可见，滚动位置将保持不变。

但是，如果页面在视口中不可见，Next.js 将滚动到第一个页面元素的顶部。如果你想禁用此行为，可以将 scroll={false} 传递给 <Link> 组件，或者在 router.push() 或 router.replace() 中传递 scroll: false。

app/page.tsx

TypeScript

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

使用 router.push() 或 router.replace()：

// useRouter
import { useRouter } from 'next/navigation'
 
const router = useRouter()
 
router.push('/dashboard', { scroll: false })

在中间件中预加载链接

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

例如，如果你想提供一个 /dashboard 路由，该路由有经过认证和访客视图，你可以在中间件中添加以下内容来将用户重定向到正确的页面：

middleware.ts

TypeScript

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

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

app/page.tsx

TypeScript

'use client'
 
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>` 标签。提供了一个代码转换工具来自动更新你的代码库。
`v10.0.0`	指向动态路由的 `href` 属性会自动解析，不再需要 `as` 属性。
`v8.0.0`	改进了预加载性能。
`v1.0.0`	引入了 `next/link`。