本教程详细介绍了如何在HTML文件中直接嵌入Mermaid图表。通过引入Mermaid JavaScript库并进行简单的初始化配置，用户可以利用文本语法在网页中渲染出各种精美图表，如流程图、序列图、甘特图等，实现动态且易于维护的文档可视化。
引言：Mermaid与HTML集成的重要性
Mermaid是一个基于JavaScript的图表和流程图工具，它使用类似Markdown的文本语法来创建各种图表，如流程图、序列图、类图、甘特图、状态图等。与传统的图形化工具不同，Mermaid允许用户通过代码来定义图表，这使得图表版本控制、协作和自动化生成变得更加容易。
虽然Mermaid常与Markdown编辑器（如Sublime Text与MarkdownPreview）结合使用，但在许多场景下，我们可能需要将这些图表直接嵌入到HTML页面中，例如在静态网站、在线文档或Web应用程序中。直接在HTML中嵌入Mermaid图表，可以实现更灵活的布局控制、更丰富的交互性，并且无需依赖外部渲染工具即可在浏览器中直接显示。
核心步骤：引入Mermaid库与初始化
要在HTML文件中嵌入Mermaid图表，主要涉及两个步骤：引入Mermaid JavaScript库，以及初始化Mermaid。
立即学习“前端免费学习笔记（深入）”；
-
引入Mermaid JavaScript库： Mermaid库可以通过CDN（内容分发网络）方便地引入到HTML文件中。通常，我们使用ESM（ECMAScript Modules）版本，因为它提供了更好的模块化和性能。将以下<script>标签放置在HTML文件的<head>或<body>标签的末尾，确保在Mermaid图表内容之前加载。
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; // 确保在渲染图表前初始化Mermaid mermaid.initialize({ startOnLoad: true }); </script>请注意，CDN链接中的版本号（例如@10）可能会更新，建议使用最新稳定版本。
-
初始化Mermaid：mermaid.initialize({ startOnLoad: true })是关键的初始化调用。
- mermaid.initialize()：这是Mermaid库提供的初始化函数，用于配置Mermaid的行为。
- startOnLoad: true：这个配置项告诉Mermaid在页面加载完成后自动扫描HTML文档中的Mermaid图表定义，并将其渲染成SVG图形。如果设置为false，则需要手动调用mermaid.render()方法来渲染图表。
编写和渲染Mermaid图表
一旦Mermaid库被引入并初始化，您就可以在HTML文档中编写Mermaid图表语法了。Mermaid会自动查找并渲染这些图表。
Mermaid图表语法通常放置在一个具有特定类名的HTML元素中，例如<pre class="mermaid">或<div class="mermaid">。Mermaid会识别这些元素中的文本内容作为图表定义。
以下是一个完整的HTML文件示例，展示了如何嵌入一个简单的流程图和一个C4组件图：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>HTML中嵌入Mermaid图表示例</title>
<!-- 引入Mermaid样式，可选，但可以提供更好的默认渲染效果 -->
<style>
.mermaid {
margin: 20px 0;
text-align: center;
}
</style>
</head>
<body>
<h1>Mermaid图表示例</h1>
<h2>流程图</h2>
<pre class="mermaid">
graph TD
A[开始] --> B{判断};
B -- 是 --> C[执行操作1];
B -- 否 --> D[执行操作2];
C --> E[结束];
D --> E;
</pre>
<h2>C4组件图</h2>
<pre class="mermaid">
C4Component
title 用户认证组件图
Component(AuthService, "认证服务", "处理用户登录、注册、授权")
Component(UserRepository, "用户仓库", "管理用户数据")
Component(TokenService, "令牌服务", "生成和验证JWT令牌")
Rel(AuthService, UserRepository, "使用", "查询/保存用户")
Rel(AuthService, TokenService, "使用", "生成/验证令牌")
</pre>
<!-- 引入Mermaid库并初始化，放置在body结束标签前以确保DOM加载完成 -->
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
// 初始化Mermaid，使其在页面加载时自动查找并渲染图表
mermaid.initialize({ startOnLoad: true });
</script>
</body>
</html>将上述代码保存为.html文件并在浏览器中打开，您将看到渲染出的流程图和C4组件图。
注意事项与最佳实践
- Mermaid版本： 始终关注Mermaid的最新稳定版本。CDN链接中的版本号（如@10）应与您希望使用的版本匹配。新版本可能引入新功能或修复bug。
- startOnLoad配置： startOnLoad: true是大多数情况下的便利选项。如果您需要在页面加载后动态添加或修改Mermaid图表，或者需要更精细的控制渲染时机，可以将其设置为false，然后手动调用mermaid.render(id, graphDefinition)方法来渲染特定的图表。
- 图表容器： 推荐使用<pre class="mermaid">或<div class="mermaid">作为Mermaid图表的容器。pre标签可以保留图表定义的格式，而div标签则更通用。Mermaid会自动识别这些类名。
- 错误处理： 如果Mermaid图表语法有误，Mermaid可能会在控制台输出错误信息，并且图表可能无法正确渲染。检查浏览器的开发者工具（F12）控制台是调试Mermaid图表的常用方法。
-
自定义配置： mermaid.initialize()方法接受一个配置对象，允许您自定义Mermaid的行为和外观，例如：
- theme: 设置图表主题（如default, forest, dark, neutral）。
- fontFamily: 指定图表使用的字体。
- securityLevel: 控制图表中的JavaScript和HTML的安全性。
- flowchart, sequence, gantt等：针对特定图表类型的配置。
mermaid.initialize({ startOnLoad: true, theme: 'forest', // 使用森林主题 flowchart: { curve: 'basis' // 流程图曲线样式 } });
- 本地安装： 对于大型项目或离线环境，您可以选择通过npm安装Mermaid并将其打包到您的项目中，而不是使用CDN。
总结
通过本教程，您应该已经掌握了在HTML文件中直接嵌入Mermaid图表的方法。这种方式不仅简化了图表在Web页面中的集成，还利用了Mermaid的文本定义优势，使得图表维护和更新变得高效。无论是构建技术文档、项目报告还是个人博客，Mermaid与HTML的结合都能为您的内容增添专业的视觉表现力。
