Link
<Link>
是一个 React 组件,它扩展了 HTML <a>
元素,以提供预取和客户端导航。它是 Next.js 中路由之间导航的主要方式。
基本用法
import Link from 'next/link'
export default function Home() {
return <Link href="/dashboard">Dashboard</Link>
}
参考
以下 props 可以传递给 <Link>
组件
属性 | 示例 | 类型 | 必需 |
---|---|---|---|
href | href="/dashboard" | 字符串或对象 | 是 |
replace | replace={false} | 布尔值 | - |
scroll | scroll={false} | 布尔值 | - |
prefetch | prefetch={false} | 布尔值 | - |
legacyBehavior | legacyBehavior={true} | 布尔值 | - |
passHref | passHref={true} | 布尔值 | - |
shallow | shallow={false} | 布尔值 | - |
locale | locale="fr" | 字符串或布尔值 | - |
须知:
<a>
标签属性,例如className
或target="_blank"
,可以作为 props 添加到<Link>
,并将传递给底层的<a>
元素。
href
(必需)
要导航到的路径或 URL。
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
将替换当前的 history 状态,而不是在浏览器的历史记录 栈中添加新的 URL。
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 将不会尝试滚动到第一个页面元素。
须知:Next.js 在管理滚动行为之前会检查
scroll: false
。如果启用了滚动,它会识别导航相关的 DOM 节点并检查每个顶级元素。所有不可滚动的元素和那些没有渲染 HTML 的元素都会被绕过,这包括粘性或固定定位的元素,以及不可见的元素,例如那些使用getBoundingClientRect
计算的元素。然后,Next.js 继续遍历兄弟元素,直到它识别出视口中可见的可滚动元素。
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>
标签或逐步采用 App Router,App Router 也支持禁用悬停时的预取。
import Link from 'next/link'
export default function Home() {
return (
<Link href="/dashboard" prefetch={false}>
Dashboard
</Link>
)
}
legacyBehavior
不再需要将 <a>
元素作为 <Link>
的子元素。添加 legacyBehavior
属性以使用旧版行为,或移除 <a>
以升级。Codemod 可用于自动升级您的代码。
须知:当
legacyBehavior
未设置为true
时,所有anchor
标签属性也可以传递给next/link
,例如className
、onClick
等。
passHref
强制 Link
将 href
属性发送给其子组件。默认为 false
。有关更多信息,请参阅传递函数式组件示例。
shallow
更新当前页面的路径,而无需重新运行 getStaticProps
、getServerSideProps
或 getInitialProps
。默认为 false
。
import Link from 'next/link'
export default function Home() {
return (
<Link href="/dashboard" shallow={false}>
Dashboard
</Link>
)
}
locale
活动区域设置会自动前置。locale
允许提供不同的区域设置。当为 false
时,href
必须包含区域设置,因为默认行为已禁用。
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>
</>
)
}
示例
以下示例演示了如何在不同场景中使用 <Link>
组件。
链接到动态路由段
对于动态路由段,使用模板字面量创建链接路径可能很方便。
例如,您可以为动态路由 pages/blog/[slug].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>
)
}
如果子组件是包裹 <a>
标签的自定义组件
如果 Link
的子组件是包裹 <a>
标签的自定义组件,则必须将 passHref
添加到 Link
。如果您正在使用像 styled-components 这样的库,则这是必需的。如果没有它,<a>
标签将没有 href
属性,这会损害您网站的可访问性,并可能影响 SEO。如果您正在使用 ESLint,则有一个内置规则 next/link-passhref
来确保正确使用 passHref
。
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 Home() {
return (
<Link href="/about" passHref legacyBehavior>
<ForwardedMyButton />
</Link>
)
}
传递 URL 对象
Link
也可以接收 URL 对象,它将自动格式化以创建 URL 字符串
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
属性来防止添加新条目,如下例所示
import Link from 'next/link'
export default function Home() {
return (
<Link href="/about" replace>
About us
</Link>
)
}
禁用滚动到页面顶部
Link
的默认行为是滚动到页面顶部。当定义了哈希值时,它将像普通的 <a>
标签一样滚动到特定的 id。要防止滚动到顶部/哈希值,可以将 scroll={false}
添加到 Link
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
路由,您可以在您的中间件中添加以下内容以将用户重定向到正确的页面
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))
}
}
}
在这种情况下,您会希望在您的 <Link />
组件中使用以下代码
'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={path}>
Dashboard
</Link>
)
}
须知:如果您正在使用动态路由,您需要调整您的
as
和href
属性。例如,如果您有一个像/dashboard/authed/[user]
这样的动态路由,您想通过中间件以不同的方式呈现它,您可以这样写:<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>
。
版本历史
版本 | 变更 |
---|---|
v13.0.0 | 不再需要子 <a> 标签。提供了一个 codemod 来自动更新您的代码库。 |
v10.0.0 | 指向动态路由的 href 属性会自动解析,不再需要 as 属性。 |
v8.0.0 | 提高了预取性能。 |
v1.0.0 | 引入了 next/link 。 |
这有帮助吗?