Link

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

基本用法

app/page.tsx

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}`	布尔值或 null	-
`onNavigate`	`onNavigate={(e) => {}}`	函数	-

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

`href`（必需）

要导航到的路径或 URL。

app/page.tsx

import Link from 'next/link'
 
// Navigate to /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

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

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

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

`onNavigate`

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

app/page.tsx

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Only executes during SPA navigation
        console.log('Navigating...')
 
        // Optionally prevent navigation
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

须知：虽然 onClick 和 onNavigate 看起来很相似，但它们服务于不同的目的。onClick 对所有点击事件执行，而 onNavigate 仅在客户端导航期间运行。一些主要区别

当使用修饰键 (Ctrl/Cmd + 点击) 时，onClick 执行，但 onNavigate 不执行，因为 Next.js 阻止新选项卡的默认导航。

外部 URL 不会触发 onNavigate，因为它仅适用于客户端和同源导航。

带有 download 属性的链接将与 onClick 一起使用，但不会与 onNavigate 一起使用，因为浏览器会将链接的 URL 视为下载。

示例

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

链接到动态段

当链接到动态段时，您可以使用模板字面量和插值来生成链接列表。例如，要生成博客文章列表

app/blog/post-list.tsx

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

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

链接到动态路由段

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

例如，您可以生成一个链接到动态路由 app/blog/[slug]/page.js 的列表

app/blog/page.tsx

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

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 中

app/page.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 Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

替换 URL 而不是推送

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

app/page.js

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> 组件，或将 scroll: false 传递给 router.push() 或 router.replace()。

app/page.tsx

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

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

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

当满足某些条件时，例如表单有未保存的更改时，您可以使用 onNavigate 属性来阻止导航。当您需要在应用中的多个组件中阻止导航时（例如在编辑表单时阻止来自任何链接的导航），React Context 提供了一种简洁的方式来共享此阻止状态。首先，创建一个上下文来跟踪导航阻止状态

app/contexts/navigation-blocker.tsx

'use client'
 
import { createContext, useState, useContext } from 'react'
 
interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}
 
export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })
 
export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)
 
  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}
 
export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

创建一个使用上下文的表单组件

app/components/form.tsx

'use client'
 
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()
 
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Save</button>
    </form>
  )
}

创建一个阻止导航的自定义 Link 组件

app/components/custom-link.tsx

'use client'
 
import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}
 
export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()
 
  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('You have unsaved changes. Leave anyway?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

创建一个导航组件

app/components/nav.tsx

'use client'
 
import { CustomLink as Link } from './custom-link'
 
export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
  )
}

最后，在根布局中使用 NavigationBlockerProvider 包装您的应用，并在您的页面中使用组件

app/layout.tsx

import { NavigationBlockerProvider } from './contexts/navigation-blocker'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

然后，在您的页面中使用 Nav 和 Form 组件

app/page.tsx

import Nav from './components/nav'
import Form from './components/form'
 
export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

当用户尝试在使用 CustomLink 导航离开，而表单有未保存的更改时，他们将被提示确认是否离开。

版本历史

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

Link

参考

`href`（必需）

`replace`

`scroll`

`prefetch`

`onNavigate`

示例

链接到动态段

检查活动链接

滚动到 `id`

链接到动态路由段

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

嵌套函数式组件

替换 URL 而不是推送

禁用滚动到页面顶部

在中间件中预取链接

阻止导航

版本历史