<連結>

<Link> 是一個 React 元件，它擴充了 HTML <a> 元素，以提供 預先提取 和路由之間的客戶端導覽。它是 Next.js 中路由之間導覽的主要方式。

基本用法

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

參考

可以將以下屬性傳遞給 <Link> 元件

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

href（必填）

要導航到的路徑或網址。

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

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

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：在進入視埠和懸停時都不會進行預取。

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

範例

以下範例示範如何在不同情境中使用 <Link> 元件。

連結到動態區段

連結到動態區段時，您可以使用樣板字面值和插值來產生連結清單。例如，要產生部落格文章清單

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 相符

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

捲動到 id

如果您想要在導覽時捲動到特定的 id，您可以將網址附加 # 雜湊連結，或只將雜湊連結傳遞給 href 屬性。這是可行的，因為 <Link> 會轉譯為 <a> 元素。

<Link href="/dashboard#settings">Settings</Link>
 
// Output
<a href="/dashboard#settings">Settings</a>

注意事項:

• 在導航時，如果頁面不在可視區域內，Next.js 會滾動到該頁面。

連結到動態路由區段

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

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

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

如果子元件是包裝 <a> 標籤的自定義元件 之類的函式庫，這是必要的。沒有這個，<a> 標籤將沒有 href 屬性，這會損害您網站的可訪問性，並可能影響 SEO。如果您正在使用 ESLint，則有一個內建規則 next/link-passhref 可確保正確使用 passHref。

components/nav-link.tsx

TypeScript

JavaScriptTypeScript

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

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，而非 push

Link 元件的預設行為是將新的 URL push 到 history 堆疊中。您可以使用 replace 屬性來防止新增新的項目，如下例所示：

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()。

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

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 /> 元件中使用以下程式碼：

app/page.tsx

TypeScript

JavaScriptTypeScript

'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 href={path}>
      Dashboard
    </Link>
  )
}

版本歷史記錄

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