logoNext.js 简体中文
文档博客学习
简介/API 参考文档/组件/Link

Link

示例

<Link> 是一个扩展了 HTML <a> 元素的 React 组件，提供 预加载 (prefetching) 和路由间的客户端导航功能。它是 Next.js 中在路由之间导航的主要方式。

例如，考虑一个包含以下文件的 pages 目录：

  • pages/index.js
  • pages/about.js
  • pages/blog/[slug].js

我们可以这样创建指向这些页面的链接：

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">首页</Link>
      </li>
      <li>
        <Link href="/about">关于我们</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">博客文章</Link>
      </li>
    </ul>
  )
}

export default Home

属性

以下是 Link 组件可用的属性概览：

属性示例类型必填
hrefhref="/dashboard"字符串或对象是
replacereplace={false}布尔值-
scrollscroll={false}布尔值-
prefetchprefetch={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 会替换当前的历史记录状态，而不是在 浏览器历史记录 (browser’s history) 栈中添加一个新 URL。

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

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

其他属性

legacyBehavior

<Link> 不再需要 <a> 元素作为子元素。添加 legacyBehavior 属性以使用旧版行为，或移除 <a> 以升级。提供 代码修改工具 (codemod) 来自动更新您的代码库。

须知：当 legacyBehavior 未设置为 true 时，所有 anchor 标签属性（如 className、onClick 等）都可以传递给 next/link。

passHref

强制 Link 将 href 属性传递给其子元素。默认为 false。

scroll

导航后滚动到页面顶部。默认为 true。

shallow

更新当前页面的路径而不重新运行 getStaticProps、getServerSideProps 或 getInitialProps。默认为 false。

locale

会自动添加当前活动的语言环境。locale 允许提供不同的语言环境。当为 false 时，href 必须包含语言环境，因为默认行为被禁用。

示例

链接到动态路由

对于动态路由，使用模板字面量创建链接路径会很方便。

例如，您可以生成指向动态路由 pages/blog/[slug].js 的链接列表：

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

如果子元素是包裹 <a> 标签的自定义组件

如果 Link 的子元素是包裹 <a> 标签的自定义组件，您必须向 Link 添加 passHref。这在您使用像 styled-components 这样的库时是必要的。否则，<a> 标签将不会有 href 属性，这会影响您网站的可访问性并可能影响 SEO。如果您使用 ESLint，有一个内置规则 next/link-passhref 来确保正确使用 passHref。

import Link from 'next/link'
import styled from 'styled-components'

// 创建一个包裹 <a> 标签的自定义组件
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'

// `onClick`、`href` 和 `ref` 需要传递给 DOM 元素
// 以便正确处理
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      点击我
    </a>
  )
})

function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

export default Home

使用 URL 对象

Link 也可以接收 URL 对象，并会自动格式化以创建 URL 字符串。示例如下：

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          关于我们
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          博客文章
        </Link>
      </li>
    </ul>
  )
}

export default Home

上述示例包含以下链接：

您可以使用 Node.js URL 模块文档 中定义的任何属性。

替换 URL 而非推送

Link 组件的默认行为是将新 URL push 到 history 栈中。您可以使用 replace 属性来阻止添加新条目，如下例所示：

<Link href="/about" replace>
  关于我们
</Link>

禁用滚动到页面顶部

Link 的默认行为是滚动到页面顶部。当定义了哈希时，它会滚动到特定的 id，就像普通的 <a> 标签一样。要阻止滚动到顶部/哈希，可以向 Link 添加 scroll={false}：

<Link href="/#hashid" scroll={false}>
  禁用滚动到顶部
</Link>

中间件 (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>
  )
}

须知：如果您使用 动态路由 (Dynamic Routes)，则需要调整 as 和 href 属性。例如，如果您有一个动态路由 /dashboard/[user]，想通过中间件以不同方式呈现，可以这样写：<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">个人资料</Link>。

版本历史

版本变更
v13.0.0不再需要子 <a> 标签。提供 代码修改工具 (codemod) 来自动更新您的代码库。
v10.0.0指向动态路由的 href 属性会自动解析，不再需要 as 属性。
v8.0.0改进预加载性能。
v1.0.0引入 next/link。

<Image>（旧版）

向后兼容的图片优化方案，使用旧版 Image 组件。

<Script>

使用内置的 `next/script` 组件优化 Next.js 应用中的第三方脚本。

On this page