Skip to main content

Markdown 编辑器及预览组件

· 6 min read
Kyle
Kyle
CTO of the Ph.D. Creative Station

本篇文章介绍了一款自主研发的 Markdown 编辑器及预览组件，支持基础 Markdown 语法、数学公式（LaTeX）、原生 HTML 标签、Mermaid 图表等多种高级功能。组件基于 react-markdown 实现，具备嵌入与浮动两种模式，支持实时预览、移动端适配、键盘与触摸操作，并对数学和图表语法错误提供友好提示。文章详细讲解了组件的功能特性、用法、依赖安装、丰富的语法示例及最佳实践，帮助开发者高效集成和使用 Markdown 编辑体验于各类文档和产品页面中。

功能说明​

本组件基于 react-markdown 实现，提供一个功能完整的 Markdown 编辑器和预览功能。用户可以在左侧的文本框中输入 Markdown 格式的文本，右侧会实时显示渲染后的效果。

支持的语法功能​

组件支持以下 Markdown 语法和扩展功能：

📝 基础 Markdown 语法​

  • 文本格式：粗体、斜体、删除线
  • 标题：支持 H1-H6 级别标题
  • 列表：有序列表、无序列表、任务列表
  • 链接和图片：内联链接、引用链接、图片嵌入
  • 代码：行内代码、代码块（支持语法高亮）
  • 引用：块引用和嵌套引用
  • 表格：GitHub 风格的表格

🔧 GitHub Flavored Markdown (GFM)​

  • 任务列表：- [ ] 和 - [x] 格式
  • 删除线：~~删除内容~~
  • 表格：管道符表格格式
  • 自动链接：URL 自动转换为链接

🧮 数学公式支持​

  • 行内公式：使用单个 $ 包围，如 $E = mc^2$
  • 块级公式：使用双 $$ 包围多行公式
  • LaTeX 语法：完整支持 LaTeX 数学符号和函数

🎨 HTML 标签支持​

  • 原生 HTML：可以直接在 Markdown 中使用 HTML 标签
  • 内联样式：支持 style 属性自定义样式
  • 复杂布局：使用 div、span 等标签创建复杂布局

📊 Mermaid 图表支持​

  • 流程图：使用 graph 语法创建流程图
  • 时序图：使用 sequenceDiagram 创建时序图
  • 甘特图：使用 gantt 创建项目进度图
  • 类图：使用 classDiagram 创建类关系图
  • 状态图：使用 stateDiagram 创建状态转换图
  • 饼图：使用 pie 创建数据饼图

使用方法​

本组件支持 嵌入模式 和 浮动模式 两种使用方式。

安装依赖​

组件使用了以下依赖包：

npm install react-markdown remark-gfm remark-math rehype-raw rehype-katex mermaid
  • react-markdown：核心 Markdown 渲染引擎
  • remark-gfm：GitHub Flavored Markdown 支持
  • remark-math：数学公式解析插件
  • rehype-raw：HTML 标签支持插件
  • rehype-katex：数学公式渲染插件
  • mermaid：图表渲染库

引入组件​

在需要使用编辑器的文件中，引入 MarkdownEditor 组件：

import MarkdownEditor from '@site/src/components/MarkdownEditor';

嵌入模式​

默认情况下，编辑器会以嵌入模式渲染。它会显示在页面的正常文档流中。

<MarkdownEditor />

在嵌入模式下，会显示一个 "Float Editor" 按钮，点击该按钮可以将编辑器切换到浮动模式。

嵌入模式的演示案例如下：

浮动模式​

你也可以通过设置 initialMode 属性，让编辑器在初始加载时就以浮动窗口的形式出现。

<MarkdownEditor initialMode="floating" />

浮动模式的演示案例如下：

在浮动模式下，你可以：

  • 通过拖动窗口顶部的标题栏来移动编辑器。
  • 点击最小化按钮将编辑器变成一个可拖动的悬浮球。
  • 点击悬浮球可以恢复编辑器窗口。
  • 点击关闭按钮（"X"）可以将编辑器恢复到嵌入模式。

语法示例​

以下是各种语法功能的示例：

基础 Markdown 语法​

# 一级标题
## 二级标题
### 三级标题

**粗体文本** 和 *斜体文本*

~~删除线文本~~

- 无序列表项 1
- 无序列表项 2
  - 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2

- [ ] 未完成任务
- [x] 已完成任务

> 这是一个引用块
> 可以有多行内容

`行内代码` 和代码块：

\`\`\`javascript
function hello() {
  console.log("Hello, World!");
}
\`\`\`

| 表头 1 | 表头 2 | 表头 3 |
|-------|-------|-------|
| 内容 1 | 内容 2 | 内容 3 |
| 内容 4 | 内容 5 | 内容 6 |

HTML 标签示例​

<div style="color: blue; background: #e6f3ff; padding: 15px; border-radius: 8px;">
  <h3 style="margin: 0 0 10px 0;">HTML 样式示例</h3>
  <p>这是一个带有 <strong>自定义样式</strong> 的 HTML 区块。</p>
  <ul>
    <li>支持嵌套 HTML 元素</li>
    <li>支持内联样式</li>
  </ul>
</div>

数学公式示例​

行内公式：质量能量方程 $E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

复杂公式：
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Mermaid 图表示例​

流程图​

时序图​

甘特图​

高级功能​

组合使用示例​

可以将多种语法功能组合使用，创建丰富的文档内容：

## 🧮 数学与图表结合

圆的面积计算：$A = \pi r^2$

计算流程：

\`\`\`mermaid
graph LR
    A[输入半径 r] --> B[计算 π × r²]
    B --> C[输出面积 A]
\`\`\`

<div style="background: #f8f9fa; padding: 20px; border-left: 4px solid #0066cc;">
  <strong>提示：</strong>这个例子展示了数学公式、Mermaid 图表和 HTML 样式的完美结合！
</div>

响应式特性​

  • 移动端适配：在移动设备上，编辑器会自动调整布局
  • 触摸支持：支持触摸拖拽和缩放操作
  • 键盘友好：完整的键盘导航支持

错误处理​

  • 数学公式错误：显示友好的错误提示
  • Mermaid 语法错误：提供详细的错误信息
  • HTML 安全性：自动过滤危险的脚本标签

最佳实践​

  1. 数学公式：使用双反斜杠 \\ 进行转义
  2. 图表设计：保持图表简洁，避免过于复杂的结构
  3. HTML 使用：谨慎使用内联样式，优先考虑组件自带的样式
  4. 性能优化：大型文档建议分段编辑，避免单次渲染过多内容