跳到主要内容

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" | String or Object | Yes | | 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 or Boolean | - | | onNavigate | onNavigate={(e) => {}} | Function | - |

提示： <a> 标签的属性（如 className 或 target="_blank"）可以作为 props 添加到 <Link> 上，并会传递给底层的 <a> 元素。

href (必填)

要导航到的路径或 URL。

pages/index.tsx
import Link from 'next/link'

// 导航到 /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 不会尝试滚动到第一个页面元素。

提示： Next.js 在管理滚动行为之前会检查 scroll: false。如果启用了滚动，它会识别导航的相关 DOM 节点并检查每个顶级元素。所有不可滚动的元素和没有渲染 HTML 的元素都会被绕过，这包括粘性定位或固定定位的元素，以及不可见的元素（如通过 getBoundingClientRect 计算的元素）。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 prop：

  • true（默认）：将预取完整路由及其数据。
  • false：在进入视口时不会发生预取，但在悬停时会发生。如果你想完全移除悬停时的预取，可以考虑使用 <a> 标签或逐步采用 App 路由，它也支持禁用悬停时的预取。
pages/index.tsx
import Link from 'next/link'

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

legacyBehavior

警告： legacyBehavior prop 将在 Next.js v16 中移除。要采用新的 <Link> 行为，请移除用作 <Link> 子元素的任何 <a> 标签。codemod 可用来帮助你自动升级代码库。

自版本 13 起，不再需要 <a> 元素作为 <Link> 组件的子元素。如果你仍然需要旧行为以兼容性原因，可以添加 legacyBehavior prop。

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

passHref

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

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 (
    <>
      {/* 默认行为：语言环境被前置 */}
      <Link href="/dashboard">Dashboard (with locale)</Link>

      {/* 禁用语言环境前置 */}
      <Link href="/dashboard" locale={false}>
        Dashboard (without locale)
      </Link>

      {/* 指定不同的语言环境 */}
      <Link href="/dashboard" locale="fr">
        Dashboard (French)
      </Link>
    </>
  )
}

onNavigate

在客户端导航期间调用的事件处理程序。处理程序接收一个包含 preventDefault() 方法的事件对象，允许你在需要时取消导航。

app/page.tsx
import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // 仅在 SPA 导航期间执行
        console.log('Navigating...')

        // 可选地阻止导航
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

提示： 虽然 onClick 和 onNavigate 可能看起来很相似，但它们服务于不同的目的。onClick 对所有点击事件执行，而 onNavigate 仅在客户端导航期间运行。一些关键差异：

  • 当使用修饰键（Ctrl/Cmd + Click）时，onClick 执行但 onNavigate 不执行，因为 Next.js 阻止新标签页的默认导航。
  • 外部 URL 不会触发 onNavigate，因为它仅用于客户端和同源导航。
  • 带有 download 属性的链接将与 onClick 一起工作，但与 onNavigate 不工作，因为浏览器会将链接的 URL 视为下载。

示例

以下示例演示了如何在不同场景中使用 <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>
  )
}

滚动到 id

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

<Link href="/dashboard#settings">Settings</Link>

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

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

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

components/nav-link.tsx
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
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 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 组件的默认行为是将新 URL push 到 history 栈中。你可以使用 replace prop 来防止添加新条目，如下例所示：

pages/index.js
import Link from 'next/link'

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

禁用滚动到页面顶部

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

pages/index.js
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))
    }
  }
}

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

pages/index.tsx
'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}>
      Dashboard
    </Link>
  )
}

提示： 如果你使用动态路由，你需要调整 as 和 href props。例如，如果你有一个像 /dashboard/authed/[user] 这样的动态路由，你想通过中间件以不同方式呈现，你会写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

版本历史

| 版本 | 变更 | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v15.4.0 | 添加 auto 作为默认 prefetch 行为的别名。 | | v15.3.0 | 添加 onNavigate API。 | | v13.0.0 | 不再需要子 <a> 标签。codemod 可用于自动更新你的代码库。 | | v10.0.0 | 指向动态路由的 href props 会自动解析，不再需要 as prop。 | | v8.0.0 | 改进了预取性能。 | | v1.0.0 | 引入 next/link。 |

最后于 更新