指令 ​

指令 ​

指令使图表作者能够在渲染之前通过更改应用的配置来改变图表的外观。

拥有指令的意义在于，在编写图表时可以使用它们，并且可以修改默认的全局和图表特定配置。因此，指令是在默认配置的基础上应用的。指令的美妙之处在于，您可以使用它们来更改特定图表的配置设置，即在个别层面上。

虽然指令允许您更改大多数默认配置设置，但出于安全原因，有些设置是不可用的。此外，您还可以选择定义一组配置，以便允许图表作者通过指令进行覆盖。

指令选项类型 ​

Mermaid 基本上支持两种类型的配置选项，可以通过指令进行覆盖。

1. 通用/顶层配置：这些配置适用于所有图表。一些最重要的顶层配置包括：

   • theme
   • fontFamily
   • logLevel
   • securityLevel
   • startOnLoad
   • secure

2. 特定图表的配置：这些配置适用于特定图表，并会影响该图表的外观和行为。例如，mirrorActors 是特定于 SequenceDiagram 的配置，用于决定是否镜像参与者。因此，此配置仅适用于 SequenceDiagram 类型。

注意： 并非所有配置选项都在此处列出。要获取所有配置选项，请参考源代码中的 defaultConfig.ts。

声明指令 ​

现在我们已经定义了可用的配置类型，我们可以学习如何声明指令。指令总是以%%符号开始和结束，中间是指令文本，例如%% {directive_text} %%。

这里指令文本的结构类似于嵌套的键值对映射或一个以init为根的JSON对象。所有通用配置都在顶层定义，而所有图表特定的配置则在更深一层定义，以图表类型作为该部分的键/根。

以下代码片段展示了一个指令的结构：

%%{
  init: {
    "theme": "dark",
    "fontFamily": "monospace",
    "logLevel": "info",
    "flowchart": {
      "htmlLabels": true,
      "curve": "linear"
    },
    "sequence": {
      "mirrorActors": true
    }
  }
}%%

你也可以在一行中定义指令，像这样：

%%{init: { **insert configuration options here** } }%%

例如，以下代码片段：

%%{init: { "sequence": { "mirrorActors":false }}}%%

注意： 作为 {argument} 传递的 JSON 对象必须是有效的键值对，并且用引号括起来，否则将被忽略。有效的键值对可以在 config 中找到。

一个简单图表的示例：

在这里，指令声明将设置logLevel为debug，并将theme设置为dark，用于渲染的mermaid图表，从而改变图表本身的外观。

注意：您可以使用'init'或'initialize'，因为两者都可以作为初始化指令。还要注意，%%init%%和%%initialize%%指令在解析后将被分组在一起。

例如，解析上述内容会生成一个单一的 %%init%% JSON 对象，如下所示，结合了两个指令并保留了为 loglevel 提供的最后一个值：

{
  "logLevel": "fatal",
  "theme": "dark",
  "startOnLoad": true
}

这将被发送到 mermaid.initialize(...) 进行渲染。

指令示例 ​

既然指令的概念已经解释清楚了，让我们看一些更多指令使用的例子：

通过指令更改主题 ​

以下代码片段将 theme 更改为 forest：

%%{init: { "theme": "forest" } }%%

可能的主题值为：default, base, dark, forest 和 neutral。默认值为 default。

示例：

通过指令更改字体 ​

以下代码片段将字体更改为 Trebuchet MS、Verdana、Arial、Sans-Serif：

%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%

示例：

通过指令更改日志级别 ​

以下代码片段将 logLevel 更改为 2：

%%{init: { "logLevel": 2 } }%%

可能的 logLevel 值为：

• 1 用于 调试,
• 2 用于 信息
• 3 表示 警告
• 4 表示 错误
• 5 表示 仅致命错误

默认值为 5。

示例：

通过指令更改流程图配置 ​

一些常见的流程图配置包括：

• htmlLabels: 真/假
• curve: 线性/曲线
• diagramPadding: 数字
• useMaxWidth: 数字

有关流程图配置的完整列表，请参阅源代码中的defaultConfig.ts。我们计划很快在文档中发布所有特定图表配置的完整列表。

以下代码片段更改了流程图配置：

%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%

这里我们只覆盖了流程图的配置，而不是通用配置，将htmlLabels设置为true，并将curve设置为linear。

通过指令更改序列图配置 ​

一些常见的序列图配置包括：

• width: 数字
• height: 数字
• messageAlign: 左, 中, 右
• mirrorActors: 布尔值
• useMaxWidth: 布尔值
• rightAngles: 布尔值
• showSequenceNumbers: 布尔值
• wrap: 布尔值

有关序列图配置的完整列表，请参阅源代码中的defaultConfig.ts。我们计划很快在文档中发布所有特定于图表的配置的完整列表。

因此，默认情况下，wrap 对于序列图的值是 false。

让我们看一个例子：

现在让我们为序列图启用换行。

以下代码片段将序列图配置中的 wrap 更改为 true：

%%{init: { "sequence": { "wrap": true} } }%%

通过将上述代码片段应用到上面的图表中，wrap 将被启用：