流程图

flowDiagram 节点以以下三种格式之一存储流程图的源文本：

• Mermaid 文本，用于流程图、序列图、甘特图、思维导图及其他 Mermaid 类型。
• draw.io XML，用于在 draw.io 编辑器中绘制的流程图。
• BPMN XML，用于 BPMN 业务流程模型。

快速入门

安装扩展包和 mermaid.js（用于绘制 Mermaid 流程图的库）。示例还使用 @tiptap/core 和 @tiptap/starter-kit；若项目尚未安装它们，也请一并安装：

npm install @tiptap-pro/extension-diagrams mermaid

然后注册 Mermaid 渲染器并插入第一个流程图：

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Diagrams, chartStyleRules, flowDiagramStyleRules } from '@tiptap-pro/extension-diagrams'
import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'

const style = document.createElement('style')
style.textContent = chartStyleRules() + flowDiagramStyleRules()
document.head.append(style)

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit,
    Diagrams.configure({
      diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
    }),
  ],
})

editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  A[Order] --> B{Paid?}\n  B -->|yes| C[Ship]',
  title: 'How an order moves',
})

流程图渲染器使用绘图库绘制流程图。您可以通过 diagramRenderers 选项传入渲染器。渲染器页面介绍了 Mermaid、Pele、draw.io 和 BPMN。Mermaid页面说明了 mermaidUrl、rendererUrl 和 ?url 导入。

流程图相关页面

Mermaid 流程图类型

Mermaid 源码的第一行指定流程图类型，例如 flowchart 或 sequenceDiagram。Mermaid 流程图支持 Mermaid 11.17 中除图表类型之外的所有类型。MERMAID_DIAGRAM_KINDS 列出这些类型，mermaidDiagramKind(source) 返回源码类型。

mermaid.js 和 Pele 两种 Mermaid 渲染器都支持此列表中的类型。对于没有已注册渲染器支持的类型，请参阅哪个渲染器绘制流程图。在流程图中编辑列出了可以直接编辑文本的类型。

图表或流程图

Mermaid 的 pie、xychart、sankey、radar 和 treemap 类型会转换为 chart 节点，并保留可编辑数据，参见 importMermaidChart。Mermaid 流程图类型列表中的其他类型都会转换为流程图。insertFlowDiagram 和 updateFlowDiagram 不接受图表源码。

流程图的存储方式

文档不会存储绘制后的流程图、它在屏幕上的尺寸或加载状态。

源是数据

源绝不会在应用的网页中作为代码运行。编写图表时，扩展会删除 %%{init: …}%% 指令和 frontmatter 块，因此文档无法更改 Mermaid 的运行方式。前面的 title 将成为图表的标题，除非您给出标题。颜色来自页面的 CSS，而不是源代码。

在 HTML 和纯文本中

在 HTML 中，流程图使用 <figure data-type="flow-diagram">。源文本保存在 <pre><code class="language-mermaid"> 中，标题保存在 <figcaption> 中。draw.io 和 BPMN 流程图分别使用 language-drawio 和 language-bpmn。

未启用扩展的 HTML 或 Markdown 导出会将源文本保留为代码块。将这些 HTML 粘贴到启用了扩展的编辑器中，即可还原流程图。

在纯文本中，Mermaid 流程图以 [diagram: title] 开头，后接源文本。其他格式的流程图则只包含 [diagram: title] 或 [diagram]，不带标题时省略 : title。

更改流程图

您可以使用 命令:

editor.commands.updateFlowDiagram({ source: 'sequenceDiagram\n  A->>B: Hello' })
editor.commands.setFlowDiagramView({ view: 'code' })

您自己的表单可以在有人键入时对每个输入调用 updateFlowDiagram。每次调用都是一个撤消步骤。

每次更改后都会重新绘制流程图。新绘制完成后，旧图形会被移除。Mermaid 源码存在语法错误时会显示错误状态和消息，直到源码修复。

编辑流程图或源码

每个流程图都有自己的视图。要一次切换所有流程图（例如 Mermaid 演示），请将 setFlowDiagramView 加入命令链：

const chain = editor.chain()
for (const { pos } of editor.storage.diagrams.listDiagrams()) {
  chain.setFlowDiagramView({ pos, view: 'code' })
}
chain.run()

列出、缩放和导出流程图

列出流程图

editor.storage.diagrams.listDiagrams() 返回每个流程图的信息：

缩放和最大化

setZoom、getZoom、setMaximized 和 getMaximized 使用流程图在文档中的位置进行操作。参见尺寸与视图。

导出

export({ pos })、exportAll() 和 exportDocx() 都会导出流程图。在 Word 中，流程图会作为 PNG 图像插入。参见导出了解选项和返回值。

mermaid.js、draw.io 和 BPMN 流程图渲染器仅在浏览器中绘制。在服务器上，export 会抛出错误，而 exportDocx 会跳过这些流程图并附上注释。Pele 的 renderPeleDiagram 仍可在服务器上绘制 Mermaid 源码。

命令

insertFlowDiagram

在当前选区或 pos 处插入流程图，并选中新流程图；若 select 为 false，则保留原选区。

editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  order[Order placed] --> ship[Shipped]',
  title: 'Order flow',
})

所选内容中的空段落会被替换。粘贴流程图源码时也会调用此命令，参见粘贴。

当 Mermaid 源码表示 pie、xychart、sankey、radar 或 treemap 图表时，或类型不在 Mermaid 流程图类型列表中（例如 zenuml），或 draw.io/BPMN 源码不是有效 XML 时，返回 false。

updateFlowDiagram

更改所选流程图或 pos 处流程图的源码、格式、标题或说明。未提供的字段保持不变。

editor.commands.updateFlowDiagram({ title: 'Order flow, revised' })

新源码不是对应格式支持的类型，或更改 format 时未同时提供 source，则返回 false，且不做任何更改。

setFlowDiagramView

切换为显示绘制后的流程图或其源码。

editor.commands.setFlowDiagramView({ view: 'code' })

视图存储在文档中，因此每个打开文档的人都会看到相同的视图。

convertCodeBlockToDiagram

将当前选区或 pos 处的代码块转换为 Mermaid 流程图，并选中新流程图。

if (editor.can().convertCodeBlockToDiagram()) editor.commands.convertCodeBlockToDiagram()

代码块中的 Mod-Enter 也会运行它，请参阅代码块中的 Mod-Enter。

代码块包含 Mermaid 图表源码，或包含其他类型的源码时，返回 false。