使用方法

🌐 Usage

Mermaid 是一个 JavaScript 工具，使用基于 Markdown 的语法来渲染可自定义的图表、图示和可视化内容。

🌐 Mermaid is a JavaScript tool that makes use of a Markdown based syntax to render customizable diagrams, charts and visualizations.

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

🌐 Diagrams can be re-rendered/modified by modifying their descriptions.

内容分发网络

🌐 CDN

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

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

🌐 Please note that you can switch versions through the dropdown box at the top right.

使用 Mermaid

🌐 Using mermaid

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

🌐 For the majority of users, Using the Live Editor would be sufficient, however you may also opt to deploy mermaid as a dependency or using the Mermaid API.

我们整理了一些关于如何使用 Mermaid 实时编辑器的视频教程。

🌐 We have compiled some Video Tutorials on how to use the Mermaid Live Editor.

在网页上安装和托管 Mermaid

🌐 Installing and Hosting Mermaid on a Webpage

使用 npm 包：

要求：

🌐 Requirements:

Node >= 16

bash

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

在网页上托管 Mermaid:

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

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

🌐 The easiest way to integrate mermaid on a web page requires two elements:

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

示例：

🌐 Example:

html

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

Mermaid（mermaid）JS 脚本。使用 script 标签作为 ESM 导入添加。

示例：

🌐 Example:

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 形式返回图表。

简单完整示例：

🌐 Simple full example:

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>

注意事项：

🌐 Notes:

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

🌐 An id attribute is also added to mermaid tags without one.

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

🌐 Mermaid can load multiple diagrams, in the same page.

试一试，把这段代码保存为 HTML 文件，然后用任意浏览器打开。（除了 Internet Explorer，请不要使用 Internet Explorer。）

小 Mermaid

🌐 Tiny Mermaid

我们提供了一个较小版本的 Mermaid，大约是完整库的一半大小。这个小版本不支持思维导图、架构图、KaTeX 渲染或懒加载。

🌐 We offer a smaller version of Mermaid that's approximately half the size of the full library. This tiny version doesn't support Mindmap Diagrams, Architecture Diagrams, KaTeX rendering, or lazy loading.

如果你需要一个没有这些功能的更轻量版本，可以使用 Mermaid Tiny。

🌐 If you need a more lightweight version without these features, you can use Mermaid Tiny.

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

🌐 Enabling Click Event and Tags in Nodes

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

🌐 A securityLevel configuration has to first be cleared. securityLevel sets the level of trust for the parsed diagrams and limits click functionality. This was introduced in version 8.2 as a security improvement, aimed at preventing malicious use.

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

securityLevel

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

价值观：

🌐 Values:

严格: (默认) 文本中的 HTML 标签已被编码，点击功能已被禁用。
antiscript：文本中允许包含 HTML 标签（仅移除 script 元素），并启用点击功能。
宽松：文本中允许使用 HTML 标签，并启用点击功能。
沙盒：在此安全级别下，所有渲染都在沙盒化的 iframe 中进行。这会阻止任何 JavaScript 在上下文中运行。这可能会影响图表的互动功能，如脚本、时序图中的弹出窗口、链接到其他标签或目标等。

信息

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

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

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

javascript

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

标签超出范围

🌐 Labels out of bounds

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

🌐 If you use dynamically loaded fonts that are loaded through CSS, such as fonts, mermaid should wait for the whole page to load (dom + assets, particularly the fonts file).

javascript

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

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

🌐 Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration in mermaid uses the window.load event to start rendering.

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

🌐 If your page has other fonts in its body those might be used instead of the mermaid font. Specifying the font in your styling is a workaround for this.

css

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

使用 `mermaid.run`

🌐 Using mermaid.run

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

🌐 mermaid.run was added in v10 and is the preferred way of handling more complex integration. By default, mermaid.run will be called when the document is ready, rendering all elements with class="mermaid".

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

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

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

🌐 Render all elements with querySelector ".someOtherClass"

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

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

🌐 Render all elements passed as an array

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

呈现所有 .mermaid 元素，同时抑制任何错误

🌐 Render all .mermaid elements while suppressing any error

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

调用 `mermaid.init` - 已弃用

🌐 Calling mermaid.init - Deprecated

警告

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

默认情况下，mermaid.init 会在文档就绪时被调用，查找所有具有 class="mermaid" 的元素。如果你在 Mermaid 加载后添加内容，或者需要对该行为进行更精细的控制，可以自行调用 init，方法如下：

🌐 By default, mermaid.init will be called when the document is ready, finding all elements with class="mermaid". If you are adding content after mermaid is loaded, or otherwise need finer-grained control of this behavior, you can call init yourself with:

一个配置对象
一些节点，作为
- 一个节点
- 类似数组的节点
- 或 W3C 选择器，用于查找你的节点

示例：

🌐 Example:

javascript

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

或者没有配置对象，直接使用 jQuery 选择器：

🌐 Or with no config object, and a jQuery selection:

javascript

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

在 webpack 中的使用

🌐 Usage with webpack

Mermaid 完全支持 webpack。这里有一个可运行的演示。

🌐 mermaid fully supports webpack. Here is a working demo.

API 使用

🌐 API usage

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

🌐 The main idea of the API is to be able to call a render function with the graph definition as a string. The render function will render the graph and call a callback with the resulting SVG code. With this approach it is up to the site creator to fetch the graph definition from the site (perhaps from a textarea), render it and place the graph somewhere in the site.

下面的示例展示了如何使用它。该示例只是将生成的 SVG 日志记录到 JavaScript 控制台中。

🌐 The example below shows an example of how this could be used. The example just logs the resulting SVG to the JavaScript console.

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 函数，如下面的示例所示。

🌐 To determine the type of diagram present in a given text, you can utilize the mermaid.detectType function, as demonstrated in the example below.

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>

绑定事件

🌐 Binding events

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

🌐 Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must add those events after the graph has been inserted into the DOM.

下面的示例代码是使用 API 时 Mermaid 的部分功能示例。该示例展示了在使用渲染 API 时如何将事件绑定到 SVG。

🌐 The example code below is an extract of what mermaid does when using the API. The example shows how it is possible to bind events to an SVG when using the API for rendering.

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 代码插入 DOM 以进行展示。
调用绑定事件的绑定函数。

一个标记渲染器示例

🌐 Example of a marked renderer

这是用于将文档从 Markdown 转换为带有 mermaid 图表的 HTML 的渲染器。

🌐 This is the renderer used for transforming the documentation from Markdown to html with mermaid diagrams in the 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 脚本标签。

🌐 Another example in CoffeeScript that also includes the mermaid script tag in the generated markup.

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

高级用法

🌐 Advanced usage

无需渲染的语法验证

🌐 Syntax validation without rendering

mermaid.parse(text, parseOptions) 函数在不渲染图表的情况下验证图表定义。

🌐 The mermaid.parse(text, parseOptions) function validates graph definitions without rendering a graph.

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

🌐 The function mermaid.parse(text, parseOptions), takes a text string as an argument and returns { diagramType: string } if the definition follows mermaid's syntax.

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

🌐 If the definition is invalid, the function returns false if parseOptions.suppressErrors is set to true. Otherwise, it throws an error.

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

🌐 The parseError function will be called when the parse function throws an error. It will not be called if parseOptions.suppressErrors is set to true.

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

🌐 It is possible to override this function in order to handle the error in an application-specific way.

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

🌐 The code-example below in meta code illustrates how this could work:

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

配置

🌐 Configuration

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

🌐 You can pass the required configuration to the mermaid.initialize call. This is the preferred way of configuring mermaid. The list of configuration objects are described in the mermaidAPI documentation.

html

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

信息

这是配置 Mermaid 的首选方式。

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

🌐 The following methods are deprecated and are kept only for backwards compatibility.

使用 Mermaid 对象

🌐 Using the mermaid object

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

🌐 It is possible to set some configuration via the mermaid object. The two parameters that are supported using this approach are:

mermaid.startOnLoad
mermaid.htmlLabels

javascript

mermaid.startOnLoad = true;

警告

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

使用方法 ​

内容分发网络 ​

使用 Mermaid ​

在网页上安装和托管 Mermaid ​

简单完整示例： ​

注意事项： ​

小 Mermaid ​

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

securityLevel ​

标签超出范围 ​

使用 mermaid.run ​

调用 mermaid.init - 已弃用 ​

在 webpack 中的使用 ​

API 使用 ​

绑定事件 ​

一个标记渲染器示例 ​

高级用法 ​

无需渲染的语法验证 ​

配置 ​

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

使用 Mermaid 对象 ​

使用方法

内容分发网络

使用 Mermaid

在网页上安装和托管 Mermaid

简单完整示例：

注意事项：

小 Mermaid

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

securityLevel

标签超出范围

使用 `mermaid.run`

调用 `mermaid.init` - 已弃用

在 webpack 中的使用

API 使用

绑定事件

一个标记渲染器示例

高级用法

无需渲染的语法验证

配置

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

使用 Mermaid 对象