HoverLink 悬停预览链接
Notion 风格的行内链接悬停预览卡片
HoverLink 悬停预览链接#
HoverLink 提供 Notion 风格的行内链接体验:链接可以点击跳转,指针悬停时会弹出目标页面的预览卡片(封面图、标题、描述、域名)。
所有元数据都在构建时抓取(复用项目内置的 OG 解析器,带 LRU 缓存),运行时零请求、零 JS,纯 CSS 实现悬停交互。
✨ 特性#
- 🖱️ 悬停预览:指针悬停 0.25s 后弹出预览卡片,避免划过时闪烁
- ⚡ 构建时抓取:OG 数据在构建时注入静态 HTML,无运行时开销
- ♿ 可访问性:键盘 Tab 聚焦(
:focus-within)同样触发预览 - 📉 优雅降级:抓取失败时自动降级为普通链接
- 🌗 主题适配:卡片颜色跟随明暗主题
📖 用法一:自动转换(推荐)#
在 Markdown / MDX 中,独占一行(一个段落)的外部链接会自动转换为悬停预览链接,无需任何组件:
推荐大家去读一读:
https://syanglee.commd效果(把指针放在链接上试试):
注意:只有「一个段落里只有这一个链接」才会触发自动转换;句子中间的行内链接保持原样。
📖 用法二:HoverLink 组件#
在 MDX 中显式使用组件,可以放在行内,也可以自定义内容:
import HoverLink from '@/components/mdx/HoverLink.astro'
我超级喜欢 Lisa 写的一篇博客,强烈推荐大家去读一读:<HoverLink href="https://syanglee.com/posts/2026-09-23/" label="SyangLee 好奇,耐心,和诚实 — BIB 回忆录" />mdx效果(行内嵌入,悬停查看预览):
我超级喜欢 Lisa 写的一篇博客,强烈推荐大家去读一读:SyangLee 好奇,耐心,和诚实 — BIB 回忆录,其中 Lisa 提出了三个我深以为然的关键词。
手动指定标题和描述#
<HoverLink
href="https://example.com"
label="示例站点"
title="自定义标题"
description="这是自定义的描述文本,会覆盖自动抓取的内容"
/>mdx隐藏封面图#
<HoverLink href="https://astro.build" label="Astro(无封面)" hideMedia />mdx效果:Astro(无封面)
📋 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__*),两者共用 - 移动端没有悬停态,链接正常点击跳转

