用法

Mermaid 是一个 JavaScript 工具，它利用基于 Markdown 的语法来渲染可定制的图表、图表和可视化。

图表可以通过修改其描述来重新渲染/修改。

CDN

https://www.jsdelivr.com/package/npm/mermaid

请注意，您可以通过右上角的下拉框切换版本。

使用 mermaid

对于大多数用户来说，使用Live Editor就足够了，但您也可以选择将mermaid作为依赖项部署或使用Mermaid API。

我们整理了一些关于如何使用Mermaid Live Editor的视频教程。

在网页上安装和托管Mermaid

使用 npm 包：

要求：

节点 >= 16

bash

# NPM
npm install mermaid
# Yarn
yarn add mermaid
# PNPM
pnpm add mermaid

在网页上托管mermaid：

注意：本主题在初学者用户指南中有更深入的探讨。

在网页上集成mermaid的最简单方法需要两个元素：

一个图形定义，位于标记为class=mermaid的标签内。

示例：

html

<pre class="mermaid">
    graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</pre>

mermaid js 脚本。使用 script 标签作为 ESM 导入添加。

示例：

html

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

按照这些指示，mermaid 在页面加载时启动，并在页面加载完成后，它将定位带有 class="mermaid" 的 pre 标签内的图形定义，并根据给定的定义返回 SVG 格式的图表。

简单完整示例:

html

<!doctype html>
<html lang="en">
  <body>
    <pre class="mermaid">
  graph LR
      A --- B
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
    </pre>
    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

注意事项:

没有id属性的mermaid标签也会添加一个id属性。

Mermaid 可以在同一页面中加载多个图表。

试试看，将此代码保存为HTML并使用任何浏览器加载它。（除了Internet Explorer，请不要使用Internet Explorer。）

启用节点中的点击事件和标签

必须先清除securityLevel配置。securityLevel设置了解析图表的信任级别，并限制了点击功能。这是在8.2版本中引入的安全改进，旨在防止恶意使用。

网站所有者有责任区分可信和不可信的用户群体，我们鼓励使用判断力。

安全级别

参数	描述	类型	是否必需	值
securityLevel	解析图表的信任级别	String	Optional	'sandbox', 'strict', 'loose', 'antiscript'

值：

strict: (默认) 文本中的HTML标签被编码，点击功能被禁用。
antiscript: 文本中的HTML标签是允许的（仅删除脚本元素）并且点击功能已启用。
loose: 文本中允许使用HTML标签，并且启用了点击功能。
sandbox: 使用此安全级别时，所有渲染都在沙盒化的iframe中进行。这可以防止任何JavaScript在上下文中运行。这可能会妨碍图表的交互功能，如脚本、序列图中的弹出窗口、链接到其他标签或目标等。

信息

这改变了mermaid的默认行为，因此在升级到8.2后，除非securityLevel未更改，否则流程图中的标签将被编码为标签，并且点击功能将被禁用。sandbox安全级别仍处于测试版本。

如果您负责图表源的安全性，您可以将securityLevel设置为您选择的值。这允许点击和标签。

要更改securityLevel，您必须调用mermaid.initialize：

javascript

mermaid.initialize({
  securityLevel: 'loose',
});

标签超出范围

如果您使用通过CSS动态加载的字体，例如字体，mermaid应等待整个页面加载完成（dom + 资源，特别是字体文件）。

javascript

$(document).ready(function () {
  mermaid.initialize();
});

不这样做很可能会导致mermaid渲染的图表标签超出边界。mermaid中的默认集成使用window.load事件来开始渲染。

如果你的页面正文中有其他字体，可能会使用这些字体而不是mermaid字体。在你的样式中指定字体是解决这个问题的一个方法。

css

pre.mermaid {
  font-family: 'trebuchet ms', verdana, arial;
}

使用 `mermaid.run`

mermaid.run 在 v10 版本中被添加，是处理更复杂集成的首选方式。默认情况下，当文档准备就绪时，mermaid.run 将被调用，渲染所有带有 class="mermaid" 的元素。

您可以通过调用await mermaid.run()来自定义该行为。

mermaid.initialize({startOnLoad: false}) 将阻止 mermaid.run 在加载后自动调用。

使用querySelector ".someOtherClass"渲染所有元素

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  querySelector: '.someOtherClass',
});

渲染所有作为数组传递的元素

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  nodes: [document.getElementById('someId'), document.getElementById('anotherId')],
});
await mermaid.run({
  nodes: document.querySelectorAll('.yetAnotherClass'),
});

渲染所有.mermaid元素，同时抑制任何错误

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  suppressErrors: true,
});

调用 `mermaid.init` - 已弃用

警告

mermaid.init 在 v10 中已被弃用，并将在未来的版本中移除。请改用 mermaid.run。

默认情况下，mermaid.init 会在文档准备就绪时被调用，查找所有带有 class="mermaid" 的元素。如果你在 mermaid 加载后添加内容，或者需要更精细地控制此行为，你可以自己调用 init，如下所示：

一个配置对象
一些节点，如
- 一个节点
- 一个类似数组的节点
- 或W3C选择器，将找到你的节点

示例：

javascript

mermaid.init({ noteMargin: 10 }, '.someOtherClass');

或者不使用配置对象，而是使用jQuery选择器：

javascript

mermaid.init(undefined, $('#someId .yetAnotherClass'));

与webpack的使用

mermaid 完全支持 webpack。这里有一个工作示例。

API 使用

API的主要思想是能够使用图形定义作为字符串调用渲染函数。渲染函数将渲染图形，并使用生成的SVG代码调用回调函数。通过这种方法，网站创建者可以从网站（可能从文本区域）获取图形定义，渲染它，并将图形放置在网站的某个位置。

下面的示例展示了如何使用此功能。该示例只是将生成的SVG记录到JavaScript控制台。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  mermaid.initialize({ startOnLoad: false });

  // Example of using the render function
  const drawDiagram = async function () {
    element = document.querySelector('#graphDiv');
    const graphDefinition = 'graph TB\na-->b';
    const { svg } = await mermaid.render('graphDiv', graphDefinition);
    element.innerHTML = svg;
  };

  await drawDiagram();
</script>

要确定给定文本中存在的图表类型，您可以使用mermaid.detectType函数，如下例所示。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  const graphDefinition = `sequenceDiagram
    Pumbaa->>Timon:I ate like a pig.
    Timon->>Pumbaa:Pumbaa, you ARE a pig.`;
  try {
    const type = mermaid.detectType(graphDefinition);
    console.log(type); // 'sequence'
  } catch (error) {
    // UnknownDiagramError
  }
</script>

绑定事件

有时生成的图表还定义了交互，如工具提示和点击事件。使用API时，必须在图表插入DOM后添加这些事件。

下面的示例代码是使用API时mermaid所做工作的摘录。该示例展示了在使用API进行渲染时如何将事件绑定到SVG。

javascript

// Example of using the bindFunctions
const drawDiagram = async function () {
  element = document.querySelector('#graphDiv');
  const graphDefinition = 'graph TB\na-->b';
  const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
  element.innerHTML = svg;
  // This can also be written as `bindFunctions?.(element);` using the `?` shorthand.
  if (bindFunctions) {
    bindFunctions(element);
  }
};

图表是通过渲染调用生成的。
生成后，渲染函数会调用提供的回调函数，在这个例子中，它被称为insertSvg。
回调函数被调用时带有两个参数，生成的图形的SVG代码和一个函数。该函数在SVG插入到DOM之后将事件绑定到SVG上。
将SVG代码插入DOM以进行展示。
调用绑定事件的绑定函数。

标记渲染器示例

这是用于将文档从Markdown转换为包含mermaid图表的html的渲染器。

javascript

const renderer = new marked.Renderer();
renderer.code = function (code, language) {
  if (code.match(/^sequenceDiagram/) || code.match(/^graph/)) {
    return '<pre class="mermaid">' + code + '</pre>';
  } else {
    return '<pre><code>' + code + '</code></pre>';
  }
};

另一个在CoffeeScript中的例子，它也在生成的标记中包含了mermaid脚本标签。

coffee

marked = require 'marked'

module.exports = (options) ->
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) ->
    if language is 'mermaid'
      html = ''
      if not hasMermaid
        hasMermaid = true
        html += '<script src="'+options.mermaidPath+'"></script>'
      html + '<pre class="mermaid">'+code+'</pre>'
    else
      @defaultCode(code, language)

  renderer

高级用法

不渲染的语法验证

mermaid.parse(text, parseOptions) 函数验证图形定义而不渲染图形。

函数 mermaid.parse(text, parseOptions) 接受一个文本字符串作为参数，如果定义遵循 mermaid 的语法，则返回 { diagramType: string }。

如果定义无效，当parseOptions.suppressErrors设置为true时，函数返回false。否则，它将抛出一个错误。

当解析函数抛出错误时，将调用parseError函数。如果parseOptions.suppressErrors设置为true，则不会调用它。

可以重写此函数以便以应用程序特定的方式处理错误。

下面的元代码示例说明了这是如何工作的：

javascript

mermaid.parseError = function (err, hash) {
  displayErrorInGui(err);
};

const textFieldUpdated = async function () {
  const textStr = getTextFromFormField('code');

  if (await mermaid.parse(textStr)) {
    reRender(textStr);
  }
};

bindEventHandler('change', 'code', textFieldUpdated);

配置

您可以将所需的配置传递给mermaid.initialize调用。这是配置mermaid的首选方式。配置对象的列表在mermaidAPI文档中有描述。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  let config = { startOnLoad: true, flowchart: { useMaxWidth: false, htmlLabels: true } };
  mermaid.initialize(config);
</script>

信息

这是配置mermaid的首选方式。

以下方法已被弃用，仅保留以保持向后兼容性。

使用 mermaid 对象

可以通过mermaid对象设置一些配置。使用此方法支持的两个参数是：

mermaid.startOnLoad
mermaid.html标签

javascript

mermaid.startOnLoad = true;

警告

这种设置配置的方式已被弃用。相反，推荐的方式是使用initialize方法。此功能仅保留用于向后兼容。

用法 ​

CDN ​

使用 mermaid ​

在网页上安装和托管Mermaid ​

简单完整示例: ​

注意事项: ​

启用节点中的点击事件和标签 ​

安全级别 ​

标签超出范围 ​

使用 mermaid.run ​

调用 mermaid.init - 已弃用 ​

与webpack的使用 ​

API 使用 ​

绑定事件 ​

标记渲染器示例 ​

高级用法 ​

不渲染的语法验证 ​

配置 ​

以下方法已被弃用，仅保留以保持向后兼容性。​

使用 mermaid 对象 ​

用法

CDN

使用 mermaid

在网页上安装和托管Mermaid

简单完整示例:

注意事项:

启用节点中的点击事件和标签

安全级别

标签超出范围

使用 `mermaid.run`

调用 `mermaid.init` - 已弃用

与webpack的使用

API 使用

绑定事件

标记渲染器示例

高级用法

不渲染的语法验证

配置

以下方法已被弃用，仅保留以保持向后兼容性。

使用 mermaid 对象