<Link>

範例

<Link> 是一個 React 元件，它擴展了 HTML 的 <a> 元素，提供預取 (prefetching) 和客戶端路由導航功能。這是 Next.js 中在路由之間導航的主要方式。

import Link from 'next/link'

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

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。

<Link href="/dashboard">儀表板</Link>

href 也可以接受物件，例如：

// 導航到 /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  關於
</Link>

`replace`

預設為 false。 當設為 true 時，next/link 會替換當前的歷史記錄狀態，而不是在瀏覽器的歷史記錄堆疊中添加新的 URL。

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      儀表板
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      儀表板
    </Link>
  )
}

`scroll`

預設為 true。 <Link> 的預設行為是滾動到新路由的頂部，或在後退和前進導航時保持滾動位置。當設為 false 時，next/link 在導航後不會滾動到頁面頂部。

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      儀表板
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      儀表板
    </Link>
  )
}

`prefetch`

預設為 true。 當設為 true 時，next/link 會在後台預取頁面（由 href 指定）。這有助於提高客戶端導航的性能。視口中的任何 <Link />（初始或通過滾動）都會被預加載。

可以通過傳遞 prefetch={false} 來禁用預取。預取僅在生產環境中啟用。

import Link from 'next/link'

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

import Link from 'next/link'

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

範例

連結到動態路由

對於動態路由，使用模板字面量來創建連結路徑會很方便。

例如，您可以生成一個指向動態路由 app/blog/[slug]/page.js 的連結列表：

app/blog/page.js

import Link from 'next/link'

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

中介軟體 (Middleware)

通常使用中介軟體 (Middleware) 進行身份驗證或其他涉及將用戶重寫到不同頁面的用途。為了讓 <Link /> 元件正確預取通過中介軟體重寫的連結，您需要告訴 Next.js 要顯示的 URL 和要預取的 URL。這是為了避免不必要的請求到中介軟體以知道要預取的正確路由。

例如，如果您想提供一個具有認證和訪客視圖的 /dashboard 路由，您可以在中介軟體中添加類似以下的內容，以將用戶重定向到正確的頁面：

middleware.js

export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', req.url))
    }
  }
}

在這種情況下，您需要在 <Link /> 元件中使用以下代碼：

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      儀表板
    </Link>
  )
}

版本歷史

版本	變更
`v13.0.0`	不再需要子元素 `<a>` 標籤。提供了一個代碼修改工具 (codemod) 來自動更新您的代碼庫。
`v10.0.0`	指向動態路由的 `href` 屬性會自動解析，不再需要 `as` 屬性。
`v8.0.0`	改進了預取性能。
`v1.0.0`	引入了 `next/link`。

On this page