markdown-link-card

English | 简体中文

Vue 3 链接预览卡片组件，支持在 Markdown 中通过自定义标签或 link-card 代码块渲染，并提供流式加载骨架与 CSS 变量主题。

安装

npm install markdown-link-card

| 包 | 说明 | |----|------| | vue ^3.5 | peer，必需 | | markstream-vue ^1.0 | 在 Markdown 中渲染时安装 | | stream-markdown | 与 markstream 配套使用时安装 |

全局注册

在应用入口注册插件并引入样式：

import { createApp } from 'vue'
import { createMarkdownLinkCardPlugin } from 'markdown-link-card'
import 'markdown-link-card/setup.css'
import App from './App.vue'

createApp(App).use(createMarkdownLinkCardPlugin()).mount('#app')

| 样式入口 | 说明 | |----------|------| | markdown-link-card/setup.css | 主题变量 + 组件样式（推荐） | | markdown-link-card/theme.css | 仅 CSS 变量 | | markdown-link-card/style.css | 仅组件样式 |

插件选项

| 选项 | 默认 | 说明 | |------|------|------| | scopeId | markdown-link-card | 自定义渲染器作用域 ID | | registerMarkdownRender | true | 是否同时注册 MarkdownRender 组件 |

createApp(App).use(
  createMarkdownLinkCardPlugin({ scopeId: 'my-app', registerMarkdownRender: false }),
)

在 Markdown 中使用

<script setup lang="ts">
import MarkdownRender from 'markstream-vue'
import { useLinkCardMarkdown } from 'markdown-link-card'

const linkCard = useLinkCardMarkdown()

const content = `
<link-card
  url="https://vuejs.org/"
  title="Vue.js"
  description="The Progressive JavaScript Framework"
/>
`
</script>

<template>
  <MarkdownRender
    v-bind="linkCard"
    :content="content"
  />
</template>

useLinkCardMarkdown() 返回 customId、customHtmlTags，可直接展开到 MarkdownRender。非组合式 API 可使用 getLinkCardMarkdownProps()。

独立使用 LinkCard

不经过 Markdown 时，直接传入卡片数据：

<script setup lang="ts">
import { LinkCard } from 'markdown-link-card'
import 'markdown-link-card/style.css'

const card = {
  url: 'https://example.com',
  title: 'Example',
  description: 'Site description',
  image: 'https://example.com/og.png',
}
</script>

<template>
  <LinkCard :card="card" />
</template>

| Prop | 类型 | 说明 | |------|------|------| | card | LinkCardData | url、title，可选 description、image | | loading | boolean | 显示加载骨架 | | unstyled | boolean | 仅保留布局，不应用默认主题色 |

Markdown 语法

HTML 标签

<link-card
  url="https://example.com"
  title="标题"
  description="描述"
  image="https://example.com/cover.png"
/>

代码块（JSON）

```link-card
{
  "url": "https://example.com",
  "title": "标题",
  "description": "描述"
}
```

流式内容

增量写入 Markdown 时，对未闭合的 <link-card> 使用占位处理：

<script setup lang="ts">
import MarkdownRender from 'markstream-vue'
import { computed, ref } from 'vue'
import {
  markdownWithLinkCardTagPlaceholder,
  useLinkCardMarkdown,
} from 'markdown-link-card'

const linkCard = useLinkCardMarkdown()
const text = ref('')
const done = ref(false)

const content = computed(() =>
  markdownWithLinkCardTagPlaceholder(text.value, !done.value),
)
</script>

<template>
  <MarkdownRender
    v-bind="linkCard"
    :content="content"
    :final="done"
  />
</template>

代码块在解析完成前会显示行内骨架；自定义标签依赖 markdownWithLinkCardTagPlaceholder 注入占位节点。

样式定制

通过 CSS 变量覆盖默认外观：

.link-card {
  --mlc-radius: 12px;
  --mlc-border-color: #e5e7eb;
  --mlc-bg: #fff;
  --mlc-title-color: #111827;
  --mlc-desc-color: #6b7280;
}

变量定义见 src/styles/theme.css（构建后同步到 dist/theme.css）。

API

| 导出 | 说明 | |------|------| | LinkCard | 链接预览卡片组件 | | LinkCardRenderer | Markdown 节点渲染器 | | LinkCardSkeleton | 加载骨架 | | createMarkdownLinkCardPlugin | Vue 插件 | | useLinkCardMarkdown | 组合式 API，返回 Markdown 集成 props | | getLinkCardMarkdownProps | 同上（非 setup） | | registerLinkCardRenderer | 手动注册渲染器 | | markdownWithLinkCardTagPlaceholder | 流式占位工具函数 |

License

MIT