完整的 API 参考、样式指南与高级示例请参阅 v3 Link 文档。本指南只关注从 HeroUI v2 的迁移。

主要变化

1. 组件结构

v2： 单个组件，通过 prop 配置图标
v3： 复合组件：使用 Link.Icon 子组件渲染图标

2. Prop 变更

v2 prop	v3 位置	说明
`showAnchorIcon`、`anchorIcon`	-	改用 `Link.Icon` 子组件配合 children
`isExternal`	-	改用 `target="_blank"` 与 `rel="noopener noreferrer"`
`size`、`color`、`isBlock`	-	已移除（请改用 Tailwind CSS）
`disableAnimation`	-	已移除
`underline`	-	已移除（请使用 Tailwind 工具类，如 `underline` 等）

3. 新增 prop

onPress —— 链接被激活（通过点击或键盘）时触发的事件处理函数。接受 (e: PressEvent) => void 回调。

结构变化

在 v2 中，Link 组件的用法：

import { Link } from "@heroui/react";

export default function App() {
  return <Link href="#">Default Link</Link>;
}

在 v3 中，Link 组件在基本场景下的使用方式保持不变：

import { Link } from "@heroui/react";

export default function App() {
  return <Link href="#">Default Link</Link>;
}

迁移示例

带图标

{/* Default icon */}
<Link showAnchorIcon href="#">
  External Link
</Link>

{/* Custom icon */}
<Link
  showAnchorIcon
  anchorIcon={<CustomIcon />}
  href="#"
>
  Custom Icon
</Link>

{/* Default icon */}
<Link href="#">
  External Link
  <Link.Icon />
</Link>

{/* Custom icon */}
<Link href="#">
  Custom Icon
  <Link.Icon>
    <CustomIcon />
  </Link.Icon>
</Link>

外部链接

<Link isExternal href="https://example.com">
  External Link
</Link>

<Link
  href="https://example.com"
  target="_blank"
  rel="noopener noreferrer"
>
  External Link
  <Link.Icon />
</Link>

下划线与偏移（v3：使用 Tailwind）

<Link href="#" underline="hover">
  Hover to underline
</Link>

<Link href="#">
  Hover to underline
</Link>
<Link href="#" className="underline underline-offset-2">
  Underline with offset
</Link>

配合路由库

import NextLink from "next/link";
import { Link } from "@heroui/react";

<Link as={NextLink} href="/about">
  About
</Link>

import NextLink from "next/link";
import { Link } from "@heroui/react";

{/* Style your router link with the same classes as Link; add an icon if needed */}
<NextLink href="/about" className="link">
  About
</NextLink>

组件结构

v3 Link 遵循以下结构：

Link (Root)
  ├── Link content (text)
  └── Link.Icon (optional)

总结

图标处理：showAnchorIcon 与 anchorIcon prop 由 Link.Icon 子组件取代
外部链接：isExternal prop 已移除——请手动设置 target 与 rel
移除 size prop：改用 Tailwind CSS 类（text-sm、text-base、text-lg）
移除 color prop：改用 Tailwind CSS 类（text-primary、text-danger 等）
移除 isBlock prop：改用 Tailwind CSS 类（block、hover:bg-surface）
下划线：不再作为 prop 提供；Link 默认在悬浮时显示下划线。请使用 Tailwind 类（underline、no-underline、underline-offset-1 等）进行自定义
路由：v3 Link 不再支持 as 或 asChild；请直接使用路由库的 Link 并配合相同的 Tailwind 类（例如 link、link__icon）保持视觉一致
移除动画：disableAnimation prop 已移除
onPress 处理函数：新增 onPress prop，可用于处理链接激活事件（点击或键盘）

Link

本页目录