<連結>

<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> 元件

屬性	範例	類型	必要
`href`	`href="/dashboard"`	字串或物件	是
`取代 (replace，替換)`	`replace={false}`	布林值	-
`捲動 (scroll)`	`scroll={false}`	布林值	-
`預取 (prefetch)`	`prefetch={false}`	布林值	-
`舊版行為 (legacyBehavior)`	`legacyBehavior={true}`	布林值	-
`傳遞 Href (passHref)`	`passHref={true}`	布林值	-
`淺層更新 (shallow)`	`shallow={false}`	布林值	-
`語系 (locale)`	`locale="fr"`	字串或布林值	-

注意事項：<a> 標籤屬性，例如 className 或 target="_blank"，可以作為屬性添加到 <Link> 中，並將傳遞到底層的 <a> 元素。

`href` (必要)

要導航到的路徑或網址。

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 將會取代目前的歷史狀態，而不是在瀏覽器歷史記錄堆疊中新增一個新的網址。

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 不會嘗試捲動到第一個頁面元素。

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> 標籤或逐步採用應用程式路由器，它也可以停用滑鼠懸停時的預先擷取。

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> 以進行升級。提供程式碼修改工具來自動升級您的程式碼。

注意事項：當 legacyBehavior 未設定為 true 時，所有 anchor 標籤屬性也可以傳遞給 next/link，例如 className、onClick 等。

`passHref`

強制 Link 將 href 屬性傳送給其子元素。預設值為 false。請參閱傳遞函式元件範例以取得更多資訊。

`scroll`

導覽後捲動到頁面頂部。預設為 true。

pages/index.tsx

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" scroll={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>
  )
}

locale

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

範例

對於動態路由區段，使用樣板字面值來建立連結路徑會很方便。

例如，您可以產生到動態路由 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>
  )
}

如果 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 中。

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 push 到 history 堆疊中。您可以使用 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))
    }
  }
}

middleware.js

import { NextResponse } from 'next/server'
 
export function middleware(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 href={path}>
      Dashboard
    </Link>
  )
}

注意事項：如果您使用的是動態路由，則需要調整您的 as 和 href 屬性。例如，如果您有一個像 /dashboard/authed/[user] 這樣的動態路由，您想透過中介軟體以不同的方式呈現，您可以這樣寫：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">個人檔案</Link>。

版本歷史

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

這有幫助嗎？

<連結>

範例 連結到動態路由區段

範例