<Link>

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

app/page.tsx

import Link from "next/link";
 
export default function Page() {
  return <Link href="/dashboard">仪表板</Link>;
}

app/page.js

import Link from "next/link";
 
export default function Page() {
  return <Link href="/dashboard">仪表板</Link>;
}

属性

以下是 Link 组件可用属性的摘要：

属性	示例	类型	是否必需
`href`	`href="/dashboard"`	字符串或对象	是
`replace`	`replace={false}`	布尔值	-
`scroll`	`scroll={false}`	布尔值	-
`prefetch`	`prefetch={false}`	布尔值或 null	-

提示： <a> 标签的属性，如 className 或 target="_blank"，可以作为 props 添加到 <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。

app/page.tsx

import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" replace>
      仪表板
    </Link>
  );
}

app/page.js

import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" replace>
      仪表板
    </Link>
  );
}

`scroll`

默认为 true。 <Link> 的默认行为是在新路由导航后滚动到页面顶部，或在后退和前进导航时保持滚动位置。当设置为 false 时，next/link 在导航后将_不会_滚动到页面顶部。

app/page.tsx

import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      仪表板
    </Link>
  );
}

app/page.js

import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      仪表板
    </Link>
  );
}

提示：

如果导航时 Page 不在视口内，Next.js 将滚动到该页面。

`prefetch`

当 <Link /> 组件进入用户的视口 (初始或通过滚动) 时，会触发预加载。Next.js 会在后台预加载和加载链接的路由 (由 href 指定) 及其数据，以提高客户端导航的性能。预加载只在生产环境中启用。

null (默认): 预加载行为取决于路由是静态的还是动态的。对于静态路由，将预加载完整的路由 (包括所有数据)。对于动态路由，将预加载部分路由，直到最近的带有 loading.js 边界的段。
true: 对于静态和动态路由，都将预加载完整的路由。
false: 无论是进入视口还是悬停，都不会进行预加载。

app/page.tsx

import Link from "next/link";
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      仪表板
    </Link>
  );
}

app/page.js

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

如果 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 而不是 push

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

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

禁用滚动到页面顶部

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

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

中间件

通常使用中间件进行身份验证或其他涉及将用户重写到不同页面的目的。为了让 <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" : "/public/dashboard";
  return (
    <Link as="/dashboard" href={path}>
      仪表板
    </Link>
  );
}

版本历史

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