Mermaid中文文档

Appearance

使用方法 ​

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

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

CDN ​

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

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

使用 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 '<CDN_URL>/mermaid@<MERMAID_VERSION>/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 '<CDN_URL>/mermaid@<MERMAID_VERSION>/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 标记（仅删除脚本元素），并且启用点击功能。
  • loose: 允许文本中的 HTML 标记，并且启用点击功能。
  • sandbox: 使用此安全级别，所有渲染都发生在沙箱 iframe 中。这可以防止任何 JavaScript 在上下文中运行。这可能会妨碍图表的交互功能，例如脚本、序列图中的弹出窗口、到其他选项卡或目标的链接等。

NOTE

这改变了 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" 的元素

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

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

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

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

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

调用 mermaid.init - 已弃用 ​

WARNING

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 });

  // 使用 render 函数的示例
  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
// 使用 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;
  // 这也可以使用 `?` 简写写成 `bindFunctions?.(element);`。
  if (bindFunctions) {
    bindFunctions(element);
  }
};
  1. 使用渲染调用生成图表。
  2. 生成后，渲染函数调用提供的回调函数，在本例中称为 insertSvg。
  3. 回调函数使用两个参数调用，生成的图表的 SVG 代码和一个函数。此函数在 SVG 插入 DOM 后 将事件绑定到 SVG。
  4. 将 SVG 代码插入 DOM 以进行呈现。
  5. 调用绑定函数以绑定事件。

标记渲染器的示例 ​

这是用于将文档从 Markdown 转换为包含 html 中 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>

NOTE

这是配置 Mermaid 的首选方法。

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

使用 mermaid 对象 ​

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

  • mermaid.startOnLoad
  • mermaid.htmlLabels
javascript
mermaid.startOnLoad = true;

WARNING

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