# md预览组件

**Repository Path**: bingbingyihao/md-preview-component

## Basic Information

- **Project Name**: md预览组件
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# md-preview-component

聊天场景的 Markdown 预览组件（Vue 3），专为 LLM / Agent 对话内容渲染设计。可作为独立 Vue 组件库复用。

## 功能特性

- **Markdown 渲染**：基于 [markdown-it](https://github.com/markdown-it/markdown-it)，支持表格、删除线（GFM 子集）、任务列表等
- **代码高亮 + 一键复制**：基于 [highlight.js](https://github.com/highlightjs/highlight.js)，深色主题，代码块带语言标签和复制按钮
- **数学公式**：基于 [KaTeX](https://katex.org/)，支持行内 `$...$` 与块级 `$$...$$`
- **流式输出光标**：`streaming` 为 `true` 时，内容末尾显示闪烁光标，适合 token 流式输出
- **XSS 防护**：默认禁止原始 HTML（`html: false`）+ [DOMPurify](https://github.com/cure53/DOMPurify) 双重兜底
- **聊天友好**：换行即换行（`breaks: true`）、裸链接自动识别、外链新窗口打开、窄屏表格横向滚动

## 目录结构

```
md-preview-component/
├── LICENSE              # Apache-2.0
├── README.md
├── code/                # npm 包根目录（Vue3 + Vite）
│   ├── src/
│   │   ├── index.js     # 库入口：组件 + 插件式安装
│   │   ├── main.js      # 演示页入口（仅 demo 使用）
│   │   ├── App.vue      # 演示页（对话模拟 + 流式渲染）
│   │   └── components/
│   │       └── ChatMarkdown.vue   # 核心组件（含全部样式，自包含）
│   ├── index.html
│   ├── package.json
│   └── vite.config.js   # 同时支持 demo dev 与组件库构建
└── .gitignore
```

## 快速开始

### 1. 本地调试演示

```bash
cd code
npm install
npm run dev
```

浏览器打开终端输出的地址（默认 http://localhost:5173），可看到对话模拟 + 流式打字机效果。

### 2. 在其他项目中使用（组件库）

#### 安装

`code/` 目录即 npm 包，任选一种方式安装：

```bash
# 方式一：本地目录直接安装（推荐，无需发布）
npm install <本仓库绝对路径>/code

# 方式二：npm link（本地开发联调）
cd <本仓库绝对路径>/code && npm link
cd <你的项目> && npm link md-preview-component

# 方式三：git 依赖（需要先把仓库推送到远端）
npm install git+https://github.com/<your-name>/md-preview-component.git
```

> 包名：`md-preview-component`，peerDependency 为 `vue@^3.3.0`，需由使用方自行安装 Vue 3。

#### 引入组件

```js
// 方式一：按需引入（推荐）
import { ChatMarkdown } from 'md-preview-component'

// 方式二：默认导出
import ChatMarkdown from 'md-preview-component'

// 方式三：插件式全局注册
import { createApp } from 'vue'
import { ChatMarkdownPlugin } from 'md-preview-component'
import App from './App.vue'

createApp(App).use(ChatMarkdownPlugin).mount('#app')
```

模板中使用：

```vue
<template>
  <div class="message">
    <ChatMarkdown :content="message.content" :streaming="isStreaming" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { ChatMarkdown } from 'md-preview-component'

const message = ref({ content: '## 你好\n\n这是一段 **markdown**。' })
const isStreaming = ref(false)

// 流式输出时：content 持续追加 token，isStreaming 保持 true 直到结束
</script>
```

> 组件的全部样式（markdown 内容样式、代码高亮、KaTeX）已随 JS 自动注入，无需额外引入 CSS 文件。

## API

### Props

| 名称 | 类型 | 默认值 | 说明 |
| ---- | ---- | ------ | ---- |
| `content` | `String` | `''` | markdown 原文，变化时自动重渲染 |
| `streaming` | `Boolean` | `false` | 流式输出中置为 `true`，内容末尾显示闪烁光标 |

### 事件 / 插槽

无。组件为纯展示组件，通过 `props` 驱动。

## 样式定制

所有 markdown 内容样式都挂在根元素 `.chat-markdown` 前缀下，覆盖时保持前缀即可：

```css
/* 例：调整正文字号与链接颜色 */
.chat-markdown { font-size: 16px; }
.chat-markdown a { color: #10b981; }
```

## 构建组件库

```bash
cd code
npm install
npm run build
```

产物输出到 `code/dist/`：

- `md-preview-component.js` — ESM（`import`）
- `md-preview-component.umd.cjs` — UMD（`require` / `<script>` 标签，全局变量 `ChatMarkdownPreview`）

`vite build` 默认即库构建；`npm run dev` 为演示页开发模式。

## 技术栈

| 依赖 | 用途 |
| ---- | ---- |
| [markdown-it](https://github.com/markdown-it/markdown-it) | Markdown 解析渲染 |
| [@traptitech/markdown-it-katex](https://github.com/traptitech/markdown-it-katex) | KaTeX 公式插件 |
| [highlight.js](https://github.com/highlightjs/highlight.js) | 代码高亮（common 子集，控制体积） |
| [dompurify](https://github.com/cure53/DOMPurify) | HTML 消毒，XSS 兜底 |
| [Vue 3](https://vuejs.org/) + [Vite](https://vitejs.dev/) | 框架与构建 |

## License

[Apache-2.0](./LICENSE)