> For AI agents: the site index is available at https://www.juniortree.com/llms.txt; this page is available as Markdown at https://www.juniortree.com/docs/integrations/hover-link-usage.md.
> Notion 风格的行内链接悬停预览卡片

## Page metadata

- **Published:** 2026-10-23
- **Source URL:** https://www.juniortree.com/docs/integrations/hover-link-usage

# HoverLink 悬停预览链接

HoverLink 提供 Notion 风格的行内链接体验：链接可以**点击跳转**，指针悬停时会弹出目标页面的**预览卡片**（封面图、标题、描述、域名）。

所有元数据都在**构建时**抓取（复用项目内置的 OG 解析器，带 LRU 缓存），运行时零请求、零 JS，纯 CSS 实现悬停交互。

## ✨ 特性

- 🖱️ **悬停预览**：指针悬停 0.25s 后弹出预览卡片，避免划过时闪烁
- ⚡ **构建时抓取**：OG 数据在构建时注入静态 HTML，无运行时开销
- ♿ **可访问性**：键盘 Tab 聚焦（`:focus-within`）同样触发预览
- 📉 **优雅降级**：抓取失败时自动降级为普通链接
- 🌗 **主题适配**：卡片颜色跟随明暗主题

## 📖 用法一：自动转换（推荐）

在 Markdown / MDX 中，**独占一行（一个段落）的外部链接**会自动转换为悬停预览链接，无需任何组件：

```md
推荐大家去读一读：

https://syanglee.com
```

效果（把指针放在链接上试试）：

https://astro.build

注意：只有「一个段落里只有这一个链接」才会触发自动转换；句子中间的行内链接保持原样。

## 📖 用法二：HoverLink 组件

在 MDX 中显式使用组件，可以放在行内，也可以自定义内容：

```mdx
import HoverLink from '@/components/mdx/HoverLink.astro'

我超级喜欢 Lisa 写的一篇博客，强烈推荐大家去读一读：<HoverLink href="https://syanglee.com/posts/2026-09-23/" label="SyangLee 好奇，耐心，和诚实 — BIB 回忆录" />
```

效果（行内嵌入，悬停查看预览）：

我超级喜欢 Lisa 写的一篇博客，强烈推荐大家去读一读：，其中 Lisa 提出了三个我深以为然的关键词。

### 手动指定标题和描述

```mdx
<HoverLink
  href="https://example.com"
  label="示例站点"
  title="自定义标题"
  description="这是自定义的描述文本，会覆盖自动抓取的内容"
/>
```

### 隐藏封面图

```mdx
<HoverLink href="https://astro.build" label="Astro（无封面）" hideMedia />
```

效果：

## 📋 Props 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `href` | `string` | (必需) | 跳转链接（http/https） |
| `label` | `string` | `undefined` | 链接显示文字，默认为链接本身；也可以用 slot 传入 |
| `title` | `string` | `undefined` | 手动指定卡片标题 |
| `description` | `string` | `undefined` | 手动指定卡片描述 |
| `hideMedia` | `boolean` | `false` | 隐藏卡片中的封面图 |
| `class` | `string` | `undefined` | 自定义类名 |

## 🔍 与 CardLink / LinkPreview 的区别

| 特性 | HoverLink | CardLink | LinkPreview |
|------|-----------|----------|-------------|
| 形态 | 行内链接 + 悬停浮层 | 紧凑块级卡片 | 大型块级卡片（带图） |
| 触发 | 悬停 / 聚焦时展示 | 始终展示 | 始终展示 |
| 自动转换 | ✅ 独占行链接自动转换 | ❌ | ❌ |
| 推荐场景 | 正文中引用他人文章 | 参考资料列表 | 文章开头展示引用 |

## ⚙️ 实现说明

- 自动转换由 `src/plugins/rehype-hover-link.ts` 完成（rehype 插件，构建时运行）
- 组件位于 `src/components/mdx/HoverLink.astro`
- 样式在 `src/assets/styles/app.css` 中（`.hover-link__*`），两者共用
- 移动端没有悬停态，链接正常点击跳转
