For AI agents: the complete site index is available at https://www.juniortree.com/llms.txt, and this page is available as Markdown at https://www.juniortree.com/docs/integrations/hover-link-usage.md.
JuniorTree

Back

HoverLink 悬停预览链接

Notion 风格的行内链接悬停预览卡片

HoverLink 悬停预览链接#

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

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

✨ 特性#

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

📖 用法一:自动转换(推荐)#

在 Markdown / MDX 中,独占一行(一个段落)的外部链接会自动转换为悬停预览链接,无需任何组件:

推荐大家去读一读:

https://syanglee.com
md

效果(把指针放在链接上试试):

https://astro.build ↗

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

在 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 参数#

参数类型默认值说明
hrefstring(必需)跳转链接(http/https)
labelstringundefined链接显示文字,默认为链接本身;也可以用 slot 传入
titlestringundefined手动指定卡片标题
descriptionstringundefined手动指定卡片描述
hideMediabooleanfalse隐藏卡片中的封面图
classstringundefined自定义类名
特性HoverLinkCardLinkLinkPreview
形态行内链接 + 悬停浮层紧凑块级卡片大型块级卡片(带图)
触发悬停 / 聚焦时展示始终展示始终展示
自动转换✅ 独占行链接自动转换❌❌
推荐场景正文中引用他人文章参考资料列表文章开头展示引用

⚙️ 实现说明#

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