NNext.js 中文网 GitHub

Link

<Link> 组件的 API 参考。

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

基本用法:

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

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

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

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

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

参考#

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

属性示例类型是否必需
hrefhref="/dashboard"String 或 Object是
asas="/post/abc"String 或 Object-
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Boolean-
shallowshallow={false}Boolean-
localelocale="fr"String 或 Boolean-
onNavigateonNavigate={(e) => {}}Function-
属性示例类型是否必需
hrefhref="/dashboard"String 或 Object是
replacereplace={false}Boolean-
scrollscroll={false}Boolean-
prefetchprefetch={false}Boolean、"auto" 或 null-
onNavigateonNavigate={(e) => {}}Function-
transitionTypestransitionTypes={['slide-in']}string[]-

小知识:像 className 或 target="_blank" 这样的 <a> 标签属性可以作为属性添加到 <Link> 上,并会传递给底层的 <a> 元素。

href(必需)#

要导航到的路径或 URL。

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

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

// 导航到 /about?name=test
export default function Page() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}
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>
  )
}
pages/index.js
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。

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

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

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

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

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

scroll#

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

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

小知识:Next.js 在管理滚动行为之前会先检查 scroll: false。如果启用了滚动,它会识别导航相关的 DOM 节点并检查每个顶层元素。所有不可滚动的元素以及没有渲染 HTML 的元素都会被跳过,这包括 sticky 或 fixed 定位的元素,以及通过 getBoundingClientRect 计算出的不可见元素。然后 Next.js 会继续遍历兄弟元素,直到找到视口中可见的可滚动元素。

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

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

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

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

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

prefetch#

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

可以将以下值传递给 prefetch 属性:

  • "auto" 或 null(默认值):预取行为取决于路由是静态还是动态。对于静态路由,将预取完整路由(包括其所有数据)。对于动态路由,将预取到最近的带有 loading.js 边界的片段为止的部分路由。
  • true:无论静态路由还是动态路由,都会预取完整路由。启用 Partial Prefetching 后,预取内容包括 App Shell 以及依赖链接 URL 数据的缓存内容。请参阅优化预取。
  • false:无论进入视口还是悬停时,都不会进行预取。

启用 Partial Prefetching 时(partialPrefetching: true):默认值会发生变化。auto 会预取每个路由的 App Shell(路由的静态和缓存内容),而不是整个页面。有关完整的变更行为,请参阅采用 Partial Prefetching。

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

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

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

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

可以将以下值传递给 prefetch 属性:

  • true(默认值):将预取完整路由及其数据。
  • false:进入视口时不会预取,但悬停时会预取。如果你也想完全取消悬停时的获取,可以考虑使用 <a> 标签,或逐步采用 App Router,它支持同时禁用悬停预取。
pages/index.tsx
import Link from 'next/link'

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

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

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>
  )
}
pages/index.js
import Link from 'next/link'

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

locale#

当前生效的 locale 会自动添加前缀。locale 允许提供不同的 locale。当为 false 时,href 必须包含 locale,因为默认行为已被禁用。

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

as#

用于修饰将显示在浏览器 URL 栏中的路径的可选修饰符。在 Next.js 9.5.3 之前,它用于动态路由,请查看我们的旧版文档以了解其工作方式。

当此路径与 href 中提供的路径不同时,将使用旧版文档中所示的旧 href/as 行为。

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>
  )
}
app/page.js
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 + 点击)时,onClick 会执行,但 onNavigate 不会,因为 Next.js 会阻止新标签页的默认导航。
  • 外部 URL 不会触发 onNavigate,因为它仅用于客户端和同源导航。
  • 带有 download 属性的链接可与 onClick 配合使用,但不适用于 onNavigate,因为浏览器会将链接的 URL 视为下载。

transitionTypes#

要应用于导航的过渡类型列表。这些类型会在导航过渡中传递给 React.addTransitionType,使 <ViewTransition> 组件能够根据导航类型应用不同的动画。

这些类型在点击链接时生效。通过浏览器后退或前进返回时不会触发视图过渡动画。请参阅浏览器历史记录导航期间的视图过渡。

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

export default function Page() {
  return (
    <Link href="/about" transitionTypes={['slide-in']}>
      About
    </Link>
  )
}
app/page.js
import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/about" transitionTypes={['slide-in']}>
      About
    </Link>
  )
}

示例#

以下示例演示如何在不同场景中使用 <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>
  )
}
app/blog/post-list.js
import Link from 'next/link'

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

检查激活的链接#

你可以使用 usePathname() 来判断链接是否处于激活状态。例如,要为激活的链接添加一个 class,可以检查当前的 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/ui/nav-links.js
'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>
  )
}

链接到动态路由片段#

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

例如,你可以生成一个指向动态路由 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>
  )
}

export default Posts
pages/blog/index.js
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>
  )
}

export default Posts

滚动到指定的 id#

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

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

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

小知识:

  • 如果导航时 Page 在视口中不可见,Next.js 会滚动到该 Page。

传递 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
pages/index.js
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 而不是 push#

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>
  )
}
app/page.js
import Link from 'next/link'

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

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

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

禁用滚动到页面顶部#

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

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

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

export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}
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():

jsx
// useRouter
import { useRouter } from 'next/navigation'

const router = useRouter()

router.push('/dashboard', { scroll: false })

Link 的默认行为是滚动到页面顶部。当定义了 hash 时,它会滚动到特定的 id,就像普通的 <a> 标签一样。要阻止滚动到顶部/hash,可以向 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>
  )
}
pages/index.tsx
import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}

使用 sticky 头部时的滚动偏移#

由于 Next.js 在查找滚动目标时会跳过 sticky 和 fixed 定位的元素,因此导航后内容可能最终位于 sticky 头部之后。例如,如果你的 layout 有一个 sticky 头部:

app/layout.tsx
import './globals.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <header className="sticky top-0 h-16 bg-white">
          
        </header>
        {children}
      </body>
    </html>
  )
}
app/layout.js
import './globals.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <header className="sticky top-0 h-16 bg-white">
          
        </header>
        {children}
      </body>
    </html>
  )
}

你可以在滚动容器上使用 scroll-padding-top 来考虑其高度:

app/globals.css
html {
  scroll-padding-top: 64px; /* 与 sticky 头部的高度保持一致 */
}

这是一个浏览器 CSS 属性,用于偏移基于滚动的定位。当 Next.js 使用原生 scrollIntoView() API 时(包括 hash 片段(#id)导航),它都会生效。或者,你也可以在单个目标元素上使用 scroll-margin-top,而不是设置全局偏移。

在 Proxy 中预取链接#

使用 Proxy 进行身份验证或其他涉及将用户重写到不同页面的操作是很常见的。为了让 <Link /> 组件能够正确预取经由 Proxy 重写的链接,你需要同时告诉 Next.js 要显示的 URL 和要预取的 URL。这是为了避免向 proxy 发起不必要的获取请求以确定正确的预取路由。

例如,如果你想提供一个同时具有已登录和访客视图的 /dashboard 路由,可以在 Proxy 中添加以下内容,将用户重定向到正确的页面:

proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.has('authToken')) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}
proxy.js
import { NextResponse } from 'next/server'

export function proxy(request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.has('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' // 你的身份验证 hook

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}
app/page.js
'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的身份验证 hook

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}
pages/index.tsx
'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的身份验证 hook

export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}
pages/index.js
'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // 你的身份验证 hook

export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

小知识:如果你使用了动态路由,你需要调整 as 和 href 属性。例如,如果你有一个像 /dashboard/authed/[user] 这样的动态路由,希望通过 proxy 以不同的方式呈现,可以这样写:<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>。

阻止导航#

当满足某些条件时(例如表单有未保存的更改),你可以使用 onNavigate 属性来阻止导航。当你需要在应用中的多个组件之间阻止导航时(例如在编辑表单时阻止任何链接的导航),React Context 提供了一种共享此阻止状态的简洁方式。首先,创建一个 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/contexts/navigation-blocker.js
'use client'

import { createContext, useState, useContext } from 'react'

export const NavigationBlockerContext = createContext({
  isBlocked: false,
  setIsBlocked: () => {},
})

export function NavigationBlockerProvider({ children }) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

创建一个使用该 context 的表单组件:

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>
  )
}
app/components/form.js
'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/custom-link.js
'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

export function CustomLink({ children, ...props }) {
  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>
  )
}
app/components/nav.js
'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>
  )
}

最后,在根 layout 中使用 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>
  )
}
app/layout.js
import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({ children }) {
  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>
  )
}
app/page.js
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 离开时,系统会提示他们进行确认。

版本历史#

VersionChanges
v16.2.0新增 transitionTypes 属性。
v15.4.0新增 auto 作为默认 prefetch 行为的别名。
v15.3.0新增 onNavigate API
v13.0.0不再需要子 <a> 标签。提供了 codemod 来自动更新你的代码库。
v10.0.0指向动态路由的 href 属性会自动解析,不再需要 as 属性。
v8.0.0改进了预取性能。
v1.0.0引入 next/link。
Next.js 中文网