Microlink SDK 完全指南：如何把任意 URL 变成精美链接预览卡片（新手入门教程）

Microlink SDK 完全指南：如何把任意 URL 变成精美链接预览卡片（新手入门教程）

【免费下载链接】sdkMake any URL embeddable. Turn any URL into a beautiful link preview.项目地址: https://gitcode.com/gh_mirrors/sdk/sdk

Microlink SDK是一款「把任意 URL 变成精美链接预览」的前端工具：粘贴一个网址，它就能自动抓取页面的标题、描述、图片、视频和音频，渲染成一张带标题、描述、封面图的漂亮卡片。项目基于 README.md 中描述的能力，提供React 组件和**原生 JavaScript（Vanilla JS）**两种版本，另外还有两个「悬停预览」包，让用户鼠标移过链接就能看到预览。

一句话看懂：它到底能做什么？

想象这样一个场景：你的博客里有一堆外部链接，读者必须点进去才知道链接背后是什么内容。Microlink SDK 可以让这些链接直接显示为「预览卡片」——标题 + 描述 + 封面图，甚至可播放的视频和音频，不用离开当前页面就能了解链接内容。

核心特性一览：

项目结构：4 个包怎么选？

这是一个 monorepo（多包仓库），由 lerna.json 管理，版本统一为 5.5.24，所有代码位于 packages/ 目录下：

核心实现分别在 packages/react/src/index.js（卡片主逻辑）、packages/vanilla/src/index.js 和 packages/hover-vanilla/src/index.js。

💡新手建议：React 项目直接用@microlink/react；没有框架就选@microlink/vanilla，只需几行 HTML 即可接入。

快速上手：三步装好并运行

第一步：安装

React 项目：

npm install @microlink/react styled-components --save

原生 JS 项目：

npm install @microlink/vanilla --save

也可以不用构建工具，直接用 CDN 引入@microlink/vanilla的dist/microlink.min.js文件。

第二步：使用

React 只需要一个组件，唯一的必填属性是url：

import Microlink from '@microlink/react' export default function App() { return <Microlink url="https://github.com" /> }

Vanilla 版则把页面上的<a>标签变成预览卡片：

<a href="https://github.com">GitHub</a> <script> microlink('a') </script>

第三步：看效果

卡片会自动请求 Microlink API 获取元数据，然后显示标题、描述和封面图。源码中卡片的核心渲染逻辑见 packages/react/src/components/Card/，媒体、内容、加载态都有独立子组件（如 CardMedia/index.js、CardContent.js）。

🧪 想直接看实际效果？项目自带演示页：原生版见 packages/vanilla/index.html，还附有 hover-vanilla 的多场景演示 packages/hover-vanilla/docs/index.html，里面有视频、音频、截图、大卡片等完整示例。

常用属性速查：按需微调卡片

所有 Props 都会传给 Microlink 组件，最常用的几个如下：

几个新手最常用的小技巧：

• 控制显示哪种媒体：media="image"只显示封面图；media="video"优先显示视频；也可以传数组['video', 'image', 'logo']表示按优先级降级。
• 让卡片与图片配色融合：加上contrast属性，卡片会自动从图片调色板中提取颜色。
• 静态模式：设置fetchData={false}+setData={{...}}，可完全禁用 API 请求、使用自己准备好的数据，非常适合服务端渲染。
• 懒加载调优：lazy={{ threshold: 0.5 }}表示卡片进入视口 50% 时才请求数据，长列表页面性能更好；lazy={false}可关闭。

悬停预览：鼠标移过链接就出现卡片

除了内嵌卡片，项目还有两个 hover 包，实现「鼠标悬停链接 → 弹出预览卡片」的效果，非常适合评论区、引用链接等场景。

React 用法：

import MicrolinkHover from '@microlink/hover-react' const Link = (props) => <a {...props} /> const HoverLink = MicrolinkHover(Link) export default function App() { return <HoverLink href="https://github.com">Hover over me!</HoverLink> }

Vanilla 版只需引入脚本后执行microlink('a')，页面上的链接就全部支持悬停预览。实现细节可以看 packages/hover-react/src/index.js——它用了一个带阴影和渐显动画的 PopOver 容器包裹卡片。

⚠️ 小提示：hover-vanilla 只会处理http:协议的外部链接（本地地址会自动被过滤），这是源码里内置的行为，避免把内页链接也变成预览卡片。

键盘快捷键与无障碍

当视频/音频卡片获得焦点时，支持这些快捷键控制播放：

播放控件的实现位于 packages/react/src/components/Card/CardMedia/Controls/，包含进度条、播放按钮、静音按钮等，可以按需参考或定制。

自定义样式：用 CSS 变量改配色

卡片内置了一批 CSS 变量，全局或单卡片覆盖即可换肤，例如：

.microlink_card { --microlink-max-width: 500px; --microlink-background-color: #fff; --microlink-border-color: #e1e8ed; --microlink-color: #181919; }

也支持通过style属性传入内联样式（圆角、阴影、字体等）。样式主题的变量定义在 packages/react/src/theme.js，可对照着覆盖。

浏览器支持与常见问题

• ✅ 支持所有现代浏览器（Chrome / Firefox / Safari / Edge 最新版）
• ✅ 懒加载依赖 IntersectionObserver，现代浏览器均内置
• ✅ React 包要求react >= 17、styled-components >= 5
• ❓请求失败时会怎样？组件会优雅降级为普通链接<a>，并在控制台输出带错误码和请求 ID 的格式化报错，方便排查（逻辑见 packages/react/src/index.js 的toFetchData）。

🚀总结：Microlink SDK 的核心卖点就是「让任意 URL 可嵌入」。React 项目一个组件搞定，原生项目一行microlink('a')搞定；配合 hover 包、CSS 变量和懒加载，几乎可以零成本提升任何页面的链接体验。

项目采用 MIT 协议（见 LICENSE.md），可自由用于商业项目。版本更新记录可参考根目录 CHANGELOG.md 及各包目录下的 CHANGELOG。

【免费下载链接】sdkMake any URL embeddable. Turn any URL into a beautiful link preview.项目地址: https://gitcode.com/gh_mirrors/sdk/sdk