本教程详细介绍了如何在HTML文件中直接嵌入和渲染Mermaid图表。通过引入Mermaid CDN库并进行简单的初始化配置，用户可以轻松地在网页中展示流程图、时序图、甘特图等多种类型的图表，无需依赖外部工具或复杂的构建流程，实现图表内容的动态化与可视化。
引言：Mermaid图表与HTML集成
Mermaid是一个基于JavaScript的图表绘制工具，它允许用户使用简洁的文本语法创建各种图表，如流程图、时序图、类图、状态图等。这些图表通常在Markdown文档中配合渲染器使用，但在许多场景下，我们需要将Mermaid图表直接嵌入到HTML页面中，以实现更灵活的展示和集成。本教程将指导您如何通过几个简单的步骤，在标准的HTML文件中实现Mermaid图表的直接渲染。
核心步骤：在HTML中嵌入Mermaid
在HTML文件中嵌入Mermaid图表主要涉及三个关键步骤：引入Mermaid库、放置Mermaid图表代码以及初始化Mermaid。
步骤一：引入Mermaid库
要让浏览器能够解析和渲染Mermaid语法，首先需要将Mermaid库引入到您的HTML文件中。最简便的方式是通过内容分发网络（CDN）引入。将以下<script>标签放置在您的HTML文件的<head>或<body>标签的末尾。
立即学习“前端免费学习笔记（深入）”；
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; // 可以在这里进行mermaid的初始化配置 </script>
说明：
- type="module"：这表示该脚本是一个ES模块，允许使用import语法。
- https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs：这是Mermaid库的CDN地址。@10表示引入Mermaid的第10个主要版本，您可以根据需要调整版本号。
步骤二：放置Mermaid图表代码
Mermaid图表代码需要放置在HTML文档的特定位置，以便Mermaid库能够识别并渲染它们。通常，建议将Mermaid语法内容放在一个带有class="mermaid"的<div>或<pre>标签中。
<pre class="mermaid">
graph TD
A[开始] --> B{决策};
B -- 是 --> C[执行操作];
B -- 否 --> D[结束];
C --> D;
</pre>说明：
- class="mermaid"：这个类名是Mermaid库识别图表内容的标准约定。当Mermaid初始化时，它会扫描带有这个类名的元素并尝试渲染其中的内容。
- graph TD ...：这是Mermaid的图表语法。上述示例是一个简单的流程图，表示从A到B，B根据条件流向C或D，C最终流向D。
步骤三：初始化Mermaid
在引入Mermaid库并放置图表代码之后，需要调用mermaid.initialize()方法来启动Mermaid的渲染过程。这个方法通常在Mermaid库加载完成后立即执行。
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>说明：
- mermaid.initialize({ startOnLoad: true });：这是初始化Mermaid的关键。startOnLoad: true配置项告诉Mermaid在页面加载完成后自动查找并渲染所有带有class="mermaid"的元素。如果您希望手动控制渲染时机，可以将其设置为false，然后通过mermaid.render()方法手动渲染。
完整示例代码
将上述所有步骤整合到一个完整的HTML文件中，您将得到以下结构：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mermaid图表嵌入示例</title>
</head>
<body>
<h1>我的Mermaid图表</h1>
<p>这是一个使用Mermaid绘制的简单流程图：</p>
<!-- 放置Mermaid图表代码 -->
<pre class="mermaid">
graph TD
A[开始] --> B{进行检查};
B -- 通过 --> C[操作成功];
B -- 失败 --> D[重试];
C --> E[完成];
D --> B;
</pre>
<p>这是另一个使用Mermaid绘制的时序图：</p>
<pre class="mermaid">
sequenceDiagram
participant 用户
participant 系统
participant 数据库
用户->>系统: 发送请求
系统->>数据库: 查询数据
数据库-->>系统: 返回数据
系统-->>用户: 显示结果
</pre>
<!-- 引入Mermaid库并初始化 -->
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>
</html>将上述代码保存为.html文件，并在浏览器中打开，您将看到Mermaid图表被正确渲染出来。
代码解析与注意事项
- ES模块导入 (import): 使用type="module"和import语句是现代JavaScript模块化的标准方式。它确保Mermaid库以异步且非阻塞的方式加载，不会影响页面内容的渲染。
- mermaid.initialize({ startOnLoad: true }): 这是最常用的初始化方式，它指示Mermaid在文档加载完成后自动扫描页面中的Mermaid代码并进行渲染。这对于大多数静态页面场景非常方便。
- 图表容器 (<pre class="mermaid">): 虽然Mermaid也可以尝试识别没有特定容器的图表代码，但使用<pre class="mermaid">或<div>等元素并指定class="mermaid"是官方推荐的最佳实践。它提供了明确的边界，有助于Mermaid更准确地识别和渲染图表，并可以利用CSS进行样式控制。
- Mermaid版本: CDN链接中的@10指定了Mermaid的主版本。在生产环境中，建议锁定到一个特定的稳定版本（例如@10.3.0）以避免因库更新带来的潜在兼容性问题。
- 多个图表: 您可以在同一个HTML文件中放置任意数量的带有class="mermaid"的图表代码块，mermaid.initialize()会一次性渲染所有这些图表。
-
高级配置: mermaid.initialize()方法接受一个配置对象，您可以自定义图表的主题、字体、颜色等。例如：
mermaid.initialize({ startOnLoad: true, theme: 'forest', // 可选 'default', 'dark', 'forest', 'neutral', 'base' flowchart: { curve: 'basis' // 流程图曲线类型 } });更多配置选项请参考Mermaid官方文档。
总结
通过本教程，您已经掌握了在HTML文件中直接嵌入Mermaid图表的方法。这种方式简单、高效，使得在网页中集成动态、美观的文本生成图表变得轻而易举。无论是技术文档、项目报告还是个人博客，Mermaid都能为您的内容增添专业的图表可视化能力。遵循上述步骤和注意事项，您将能够轻松地在任何HTML页面中展示您的Mermaid图表。
