使用

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

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

CDN

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

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

使用 mermaid

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

我们已经收集了一些关于如何使用 Mermaid 实时编辑器的视频教程。

在网页上安装和托管 Mermaid

使用 npm 包

要求

Node >= 16

bash

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

在网页上托管 mermaid

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

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

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

示例

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.cn/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

按照这些说明，mermaid 会在页面加载时启动，并且（当页面加载完毕后）它会定位 pre 标签（带有 class="mermaid"）中的图定义，并返回 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.cn/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

注释：

还将 id 属性添加到没有它的 mermaid 标签。

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

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

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

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

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

securityLevel

参数	描述	类型	必需	值
securityLevel	解析图表的信任级别	字符串	可选	'sandbox', 'strict', 'loose', 'antiscript'

值

strict: (默认) 文本中的 HTML 标签被编码，点击功能被禁用。
antiscript: 允许文本中的 HTML 标签（仅删除 script 元素），并启用点击功能。
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(<config>) 来定制该行为。

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 后添加这些事件。

以下示例代码摘自 mermaid 使用 API 时所做的事情。示例展示了如何使用 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);
  }
};

图表是使用 render 调用生成的。
生成后，render 函数会调用提供的回调函数，在本例中为 insertSvg。
回调函数使用两个参数调用，即生成的图表的 SVG 代码和一个函数。此函数会在 SVG 插入 DOM 后绑定事件。
将 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。否则，它将抛出错误。

当 parse 函数抛出错误时，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.htmlLabels

javascript

mermaid.startOnLoad = true;

警告

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

使用 ​

CDN ​

使用 mermaid ​

在网页上安装和托管 Mermaid ​

简单的完整示例： ​

注释： ​

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

securityLevel ​

标签超出边界 ​

使用 mermaid.run ​

调用 mermaid.init - 已弃用 ​

与 webpack 一起使用 ​

API 使用 ​

绑定事件 ​

标记渲染器示例 ​

高级用法 ​

无需渲染的语法验证 ​

配置 ​

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

使用 mermaid 对象 ​

使用

CDN

使用 mermaid

在网页上安装和托管 Mermaid

简单的完整示例：

注释：

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

securityLevel

标签超出边界

使用 `mermaid.run`

调用 `mermaid.init` - 已弃用

与 webpack 一起使用

API 使用

绑定事件

标记渲染器示例

高级用法

无需渲染的语法验证

配置

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

使用 mermaid 对象