Web编程技术营地
研究、演示、创新

Mermaid快速起步

撰写时间：2023-09-04

修订时间：2025-09-20

Mermaid将图表分为具体细类，并使用不同的语法来实现。它所支持的图表类型有：

正因为有了详细的分类，因此在制作相应的图表时，相对于其他通用的作图软件，Mermaid有巨大的优势。本站首页上的时序图，即用Mermaid来制作。其源代码可见这里。

Mermaid结合了Markdown的语法来绘制图表。

网页版Mermaid

第一步，先从CDN加载所需的JavaScript模板库，并进行初始化。

<script type="module"> import mermaid from 'https://esm.run/mermaid'; mermaid.initialize({ startOnLoad: true, theme: 'dark' }); </script>

https://esm.run/是https://www.jsdelivr.com/所提供的ESM服务的网站。但在国内访问时，速度不一定是最快的。如果是这种情况，我们也可以使用https://unpkg.com/所提供的服务：

<script type="module"> import mermaid from 'https://unpkg.com/mermaid/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'dark' }); </script>

也可使用：

<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'; mermaid.initialize({ startOnLoad: true, theme: 'dark' }); </script>

或者：

<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'dark' }); </script>

目前来看，最后这种方式比较可靠，且浏览器终端不会产生警示信息。

导入mermaid后，调用其initialize方法，传入一个对象作为参数以初始化其状态。

当参数startOnLoad的值为true时，将自动搜索网页上所有class为mermaid的pre标签，并将它们的内容渲染为SVG。

参数theme可用以指定亮色或暗色主题。这一点很方便。

第二步，编写代码：

<pre class="mermaid"> graph LR A --> B </pre>

默认情况下，Mermaid的代码放在pre元素中，并且将其class属性设置为mermaid。将显示以下效果：

                        graph LR
                            A --> B

上面两个字符实际上被置于p标签中，在与我们自己的网页整合时，如果发现位置未居中，则可通过相应的CSS来进一步矫正：

svg p { text-indent: unset; line-height: unset; }

这种方式非常简单，且适用于网页中同时存在多个pre元素的情况，但如果我们想拥有更多的自由，如自行决定渲染哪种标签、何时开始渲染等，则需要深入到了解如何调用其APIs的具体细节。

手工渲染

下面，我们手工渲染。

const {default: mermaid} = await import('https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs'); const {getCurrColorTheme} = await import('/js/esm/color-scheme.js'); mermaid.initialize({startOnLoad: false, theme: getCurrColorTheme()}); const svgId = 'my-svg'; const graphSrc = ` graph LR a-->b `; mermaid.render(svgId, graphSrc).then(obj => { const {diagramType, svg: svgStr} = obj; pc.log(diagramType); let targetDiv = pc.appendHTMLStr('
')[0]; targetDiv.outerHTML = svgStr; });

首先，当调用import函数导入模块时，所获取到的模块有一个名为default的对象，我们将其重新命名为mermaid。

其次，调用mermaid的initialize方法时，将参数中对象的属性startOnLoad的值设为false，则Mermaid不再自动搜索相应的标签并自动转换。

因这里讲解Mermaid的基本使用方法，因此未加入响应颜色主题变换的代码。当切换颜色主题时，重新刷新网页即可。自动响应颜色主题变换功能，详见High Lighting all TrimPres in a Page。

第三，mermaid的render方法中，第一个参数用以设置所生成SVG的id值，第二个参数是需渲染的源代码。

第四，render方法返回一个Promise对象。经解析后，该对象有两个重要属性。属性diagramType以字符串存储了图表类型。上面源代码graph，将渲染为flowchart，v2是其版本号。属性svg的值是是转换为SVG后的字符串。注意，它不是svg元素，而是代表整个svg元素内容的字符串。因此我们上面将其赋值给一个名为svgStr的变量。

最后，在输出面板中创建一个div标签，这是一个占位标签，其outerHTML属性值最终被替换为所生成的svgStr的值。

需提出的是，在最后生成的SVG结果中，各个节点的父元素都有一个foreignobject标签，这意味着即使所生成的svg标签虽位于Web组件中，但各节点依旧受宿主环境的CSS设置的影响。如上节所述，当我们在网页端进行了全局设置：

svg p { text-indent: unset; line-height: unset; }

则所有Web组件中的各个节点的位置不居中的问题均可得到解决。

MermaidEditor

清楚了上面的技术细节，我创建了一个MermaidEditor的类，以方便后面的学习与研究。

参考资源

  1. mermaid.js.org
  2. Mermaid Config Schema