markdown-flow-ui-vue

A Vue3 UI library for rendering markdown with interactive flow components, typewriter effects, and plugin support.

🚧 注意: 这是原 React 库 markdown-flow-ui 的 Vue3 移植版本。

特性

• ✨ 实时 Markdown 渲染，支持语法高亮
• ⌨️ 打字机效果动画
• 🎮 交互式组件，支持单选和多选
• 🔌 插件系统，支持自定义组件
• 📡 支持 SSE (Server-Sent Events) 流式内容
• 📊 Mermaid 图表渲染
• ➗ KaTeX 数学公式
• 🌍 国际化 (i18n) 支持

安装

pnpm add markdown-flow-ui-vue
# 或
npm install markdown-flow-ui-vue
# 或
yarn add markdown-flow-ui-vue

快速开始

<template>
  <div>
    <ContentRender
      :content="markdownContent"
      :enable-typewriter="true"
      :typing-speed="50"
      :on-send="handleSend"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { ContentRender } from 'markdown-flow-ui-vue'
import 'markdown-flow-ui-vue/style.css'

const markdownContent = ref('# Hello World\n\n这是 **markdown** 内容!')

function handleSend(data) {
  console.log('用户交互:', data)
}
</script>

技术栈

• 框架: Vue 3.5+ (Composition API)
• 构建工具: Vite 7.2
• UI 库: Element Plus 2.8
• CSS: Tailwind CSS 4
• Markdown: markdown-it 14.1
• 编辑器: CodeMirror 6
• 语法高亮: highlight.js 11.11
• 数学公式: KaTeX 0.16 (via @vscode/markdown-it-katex)
• 图表: Mermaid 11.4
• 工具库: @vueuse/core
• 包管理器: pnpm

交互变量语法

单选模式

使用单个 | 分隔选项：

选择你的角色: ?[%{{role}}开发者|设计师|产品经理]

多选模式

使用双 || 分隔选项：

选择技能: ?[%{{skills}}React||Vue||Angular||Node.js]

文本输入模式

使用 ... 前缀表示文本输入：

输入你的名字: ?[%{{name}}...请输入名字]

混合模式 (多选 + 文本输入)

结合多选和文本输入：

选择技术栈: ?[%{{tech}}前端||后端||移动端||...其他技术]

组件

ContentRender

核心渲染组件，支持打字机效果和交互式变量。

Props:

• content (String, 必需): 要渲染的 Markdown 内容
• enableTypewriter (Boolean): 启用打字机动画，默认 false
• typingSpeed (Number): 打字速度（毫秒/字符），默认 30
• onSend (Function): 用户交互回调函数
• confirmButtonText (String): 多选确认按钮文本，默认 'Confirm'
• readonly (Boolean): 只读模式，禁用交互，默认 false
• defaultInputText (String): 文本输入的默认值
• defaultSelectedValues (Array): 多选的默认选中值
• onTypeFinished (Function): 打字机效果完成后的回调
• customRenderBar (Component): 自定义渲染栏组件
• dynamicInteractionFormat (String): 动态交互格式

示例:

<ContentRender
  content="# 标题\n\n选择角色: ?[%{{role}}开发者|设计师]"
  :enable-typewriter="true"
  :typing-speed="50"
  :on-send="handleSend"
  confirm-button-text="确认"
/>

MarkdownFlow

流式 Markdown 渲染，支持多个内容块按顺序渲染。

Props:

• initialContentList (Array): 内容块数组，每个对象包含：
  • content (String): Markdown 内容
  • isFinished (Boolean): 是否已完成渲染
  • readonly (Boolean): 是否只读
  • defaultInputText (String): 默认输入文本
  • defaultSelectedValues (Array): 默认选中值
• enableTypewriter (Boolean): 启用打字机效果，默认 false
• typingSpeed (Number): 打字速度，默认 30
• onSend (Function): 用户交互回调
• onBlockComplete (Function): 块完成渲染的回调
• confirmButtonText (String): 确认按钮文本
• customRenderBar (Component): 自定义渲染栏

示例:

<MarkdownFlow
  :initial-content-list="[
    { content: '# 第一块', isFinished: false },
    { content: '## 第二块', isFinished: false },
  ]"
  :enable-typewriter="true"
  :on-send="handleSend"
  :on-block-complete="onBlockComplete"
/>

ScrollableMarkdownFlow

带自动滚动功能的可滚动容器，适合聊天界面等场景。

Props:

• initialContentList (Array): 同 MarkdownFlow
• height (String | Number): 容器高度，默认 '100%'
• className (String): 自定义 CSS 类名
• enableTypewriter (Boolean): 启用打字机效果
• typingSpeed (Number): 打字速度
• onSend (Function): 用户交互回调
• onBlockComplete (Function): 块完成回调
• confirmButtonText (String): 确认按钮文本

特性:

• 自动滚动到底部
• 用户向上滚动时显示"回到底部"按钮
• 使用 useScrollToBottom composable

示例:

<ScrollableMarkdownFlow
  :initial-content-list="contentList"
  :height="500"
  :enable-typewriter="true"
/>

MarkdownFlowEditor

基于 CodeMirror 6 的 Markdown 编辑器，支持斜杠命令、变量插入、图片和视频插入。

Props:

• content (String): 编辑器内容（使用 v-model:content）
• editMode (EditMode): 编辑模式，EditMode.CodeEdit 或 EditMode.QuickEdit
• variables (Array): 自定义变量列表，格式: [{ name: 'var', label: '变量' }]
• systemVariables (Array): 系统变量列表，格式同上
• locale (String): 语言设置，'zh-CN' 或 'en-US'，默认 'zh-CN'

事件:

• @change: 内容变化时触发，参数为新内容

斜杠命令:

• /image - 插入图片
• /video - 插入视频
• /variable - 插入变量

示例:

<template>
  <MarkdownFlowEditor
    v-model:content="editorContent"
    :edit-mode="EditMode.QuickEdit"
    :variables="customVars"
    locale="zh-CN"
    @change="onContentChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { MarkdownFlowEditor, EditMode } from 'markdown-flow-ui-vue'

const editorContent = ref('# 开始编辑...')
const customVars = ref([
  { name: 'userName', label: '用户名' },
  { name: 'email', label: '邮箱' },
])

function onContentChange(newContent) {
  console.log('内容更新:', newContent)
}
</script>

Composables

useTypewriter

打字机效果 hook，用于实现逐字显示动画。

参数:

{
  content: Ref<String>,      // 要显示的内容
  typingSpeed: Ref<Number>,  // 打字速度（毫秒/字符）
  disabled: Ref<Boolean>     // 是否禁用打字机效果
}

返回值:

{
  displayContent: Ref<String>,  // 当前显示的内容
  isTyping: Ref<Boolean>,       // 是否正在打字
  isComplete: Ref<Boolean>,     // 是否完成
  reset: Function,              // 重置函数
  start: Function               // 开始打字函数
}

useScrollToBottom

自动滚动到底部的 hook，用于聊天界面等场景。

参数:

containerRef: Ref<HTMLElement>,  // 容器元素引用
dependencies: Array<Ref>,        // 监听依赖项
options: {
  behavior: 'smooth' | 'auto',   // 滚动行为
  autoScrollOnInit: Boolean,     // 初始化时自动滚动
  scrollDelay: Number            // 滚动延迟（毫秒）
}

返回值:

{
  showScrollToBottom: Ref<Boolean>,  // 是否显示"回到底部"按钮
  handleUserScrollToBottom: Function // 手动滚动到底部的函数
}

API 导出

// 组件
import {
  ContentRender,
  MarkdownFlow,
  ScrollableMarkdownFlow,
  MarkdownFlowEditor,
  CustomVariable,
  MermaidChart,
} from 'markdown-flow-ui-vue'

// Composables
import { useTypewriter, useScrollToBottom } from 'markdown-flow-ui-vue'

// 类型和枚举
import { EditMode, SelectedOption } from 'markdown-flow-ui-vue'

// 样式
import 'markdown-flow-ui-vue/style.css'

演示

本项目包含完整的演示应用，展示所有功能：

# 克隆仓库
git clone https://github.com/ai-shifu/markdown-flow-ui-vue.git
cd markdown-flow-ui-vue

# 安装依赖
pnpm install

# 启动演示应用
pnpm dev

演示应用包含 6 个 Tab：

1. 基础渲染 - 基础 Markdown 渲染功能
2. 打字机效果 - 逐字显示动画演示
3. 交互变量 - 单选/多选/文本输入/混合模式
4. 高级功能 - 代码高亮、数学公式、Mermaid 图表、表格
5. Markdown 编辑器 - CodeMirror 编辑器演示
6. 流式渲染 - MarkdownFlow 和 ScrollableMarkdownFlow 演示

开发

# 安装依赖
pnpm install

# 启动开发服务器（查看演示）
pnpm dev

# 构建库（用于发布）
pnpm build

# 或使用库模式构建
pnpm build:lib

# 代码检查
pnpm lint

# 自动修复代码问题
pnpm lint:fix

# 代码格式化
pnpm format

# 检查代码格式
pnpm format:check

项目状态

✅ 已完成功能

核心组件

• ✅ ContentRender - 核心 Markdown 渲染组件

  • 支持打字机效果
  • 交互式变量（单选/多选/文本输入/混合模式）
  • 自定义渲染栏
  • 语法高亮（highlight.js）
  • 数学公式（KaTeX）
  • Mermaid 图表

• ✅ MarkdownFlow - 多块流式渲染组件

  • 按顺序渲染多个内容块
  • 每个块独立的打字机效果控制
  • 块完成回调
  • 支持 per-block 配置

• ✅ ScrollableMarkdownFlow - 可滚动容器组件

  • 自动滚动到底部
  • "回到底部"按钮
  • 流畅的滚动动画
  • 适合聊天界面场景

• ✅ MarkdownFlowEditor - CodeMirror 6 编辑器

  • 斜杠命令系统（/image, /video, /variable）
  • 图片/视频插入和编辑
  • 变量管理和插入
  • QuickEdit 模式（可视化占位符）
  • CodeEdit 模式（纯代码）
  • 国际化支持（中英文）

Composables

• ✅ useTypewriter - 打字机效果 hook

  • 逐字显示动画
  • 可配置速度
  • 完成回调

• ✅ useScrollToBottom - 自动滚动 hook

  • 自动滚动检测
  • 用户滚动检测
  • 防抖处理

插件系统

• ✅ CustomVariable - 交互式变量组件
• ✅ MermaidChart - 图表渲染组件
• ✅ markdown-it 插件 - 自定义语法解析

基础设施

• ✅ 项目结构和配置
• ✅ Vite 构建配置（库模式）
• ✅ Tailwind CSS 4 集成
• ✅ ESLint + Prettier 配置
• ✅ Element Plus 集成
• ✅ 完整的演示应用（6个 Tab）
• ✅ 详细的文档（README + CLAUDE.md + EDITOR_GUIDE.md）

📊 功能对比（与 React 版本）

| 功能 | React 版本 | Vue3 版本 | 状态 | | ---------------------- | ---------- | --------- | ------- | | 基础 Markdown 渲染 | ✅ | ✅ | ✅ 完成 | | 打字机效果 | ✅ | ✅ | ✅ 完成 | | 交互式变量 | ✅ | ✅ | ✅ 完成 | | 多选变量 | ✅ | ✅ | ✅ 完成 | | Mermaid 图表 | ✅ | ✅ | ✅ 完成 | | 代码高亮 | ✅ | ✅ | ✅ 完成 | | 数学公式 (KaTeX) | ✅ | ✅ | ✅ 完成 | | MarkdownFlow | ✅ | ✅ | ✅ 完成 | | ScrollableMarkdownFlow | ✅ | ✅ | ✅ 完成 | | MarkdownFlowEditor | ✅ | ✅ | ✅ 完成 | | 斜杠命令 | ✅ | ✅ | ✅ 完成 | | 变量插入 | ✅ | ✅ | ✅ 完成 | | 国际化 | ✅ | ✅ | ✅ 完成 |

🚧 待完成

• ⚠️ 单元测试 - 尚未实现测试用例（计划使用 Vitest）
• ⚠️ npm 发布准备 - 缺少以下文件：
  • LICENSE 文件
  • .npmignore 文件
  • CHANGELOG.md
  • Husky + lint-staged 配置

🎯 下一步计划

1. 添加单元测试和集成测试
2. 完善 npm 发布配置
3. 发布到 npm 仓库
4. 添加更多示例和文档

许可证

MIT

致谢

原 React 版本: markdown-flow-ui by AI Shifu