跳到内容

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

参考

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

属性示例类型必需
hrefhref="/dashboard"字符串或对象
替换replace={false}布尔值-
滚动scroll={false}布尔值-
预加载prefetch={false}布尔值-
旧版行为legacyBehavior={true}布尔值-
传递 hrefpassHref={true}布尔值-
浅层shallow={false}布尔值-
区域设置locale="fr"字符串或布尔值-
onNavigateonNavigate={(e) => {}}函数-

须知<a> 标签属性(例如 classNametarget="_blank")可以作为属性添加到 <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 将不会尝试滚动到第一个页面元素。

须知: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 属性

  • true(默认):将预加载完整的路由及其数据。
  • false:进入视口时不会发生预加载,但在悬停时会发生预加载。 如果您想完全移除悬停时的获取,请考虑使用 <a> 标签或逐步采用 App Router,App Router 也支持禁用悬停时的预加载。
pages/index.tsx
import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

legacyBehavior

不再需要将 <a> 元素作为 <Link> 的子元素。 添加 legacyBehavior 属性以使用旧版行为,或移除 <a> 以进行升级。 codemod 可用于自动升级您的代码。

须知:当 legacyBehavior 未设置为 true 时,所有 anchor 标签属性也可以传递给 next/link,例如 classNameonClick 等。

passHref

强制 Linkhref 属性发送到其子组件。 默认为 false。 有关更多信息,请参阅传递函数式组件示例。

shallow

更新当前页面的路径,而无需重新运行 getStaticPropsgetServerSidePropsgetInitialProps。 默认为 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>
    </>
  )
}

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

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

  • 当使用修饰键(Ctrl/Cmd + 点击)时,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>
  )
}

如果子组件是包装 <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 的子组件是函数式组件,除了使用 passHreflegacyBehavior 之外,您还必须将组件包装在 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 组件的默认行为是将新 URL pushhistory 堆栈中。 您可以使用 replace 属性来防止添加新条目,如下例所示

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

禁用滚动到页面顶部

Link 的默认行为是滚动到页面顶部。 当定义了哈希值时,它将滚动到特定的 id,就像普通的 <a> 标签一样。 要阻止滚动到顶部/哈希值,可以将 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))
    }
  }
}

在这种情况下,您需要在 <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={path}>
      Dashboard
    </Link>
  )
}

须知:如果您正在使用 动态路由,您需要调整您的 ashref 属性。 例如,如果您有一个像 /dashboard/authed/[user] 这样的动态路由,您想通过中间件以不同的方式呈现它,您应该这样写: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</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>
  )
}

然后,在您的页面中使用 NavForm 组件

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