指令

¥Directives

WARNING

Directives are deprecated from v10.5.0. Please use the config key in frontmatter to pass configuration. See Configuration for more details.

指令

¥Directives

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

¥Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.

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

¥The significance of having directives is that you have them available while writing the diagram, and can modify the default global and diagram-specific configurations. So, directives are applied on top of the default configuration. The beauty of directives is that you can use them to alter configuration settings for a specific diagram, i.e. at an individual level.

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

¥While directives allow you to change most of the default configuration settings, there are some that are not available, for security reasons. Also, you have the option to define the set of configurations that you wish to allow diagram authors to override with directives.

指令选项类型

¥Types of Directives options

Mermaid 基本上支持两种类型的配置选项以被指令覆盖。

¥Mermaid basically supports two types of configuration options to be overridden by directives.

1. 常规/顶层配置：这些是可用并应用于所有图表的配置。一些最重要的顶层配置是：

   ¥General/Top Level configurations : These are the configurations that are available and applied to all the diagram. Some of the most important top-level configurations are:

   • theme

   • fontFamily

   • logLevel

   • securityLevel

   • startOnLoad

   • secure

2. 图特定配置：这些是可用并应用于特定图的配置。对于每个图，都有特定的配置，这些配置将改变特定图的外观和行为。例如，mirrorActors 是特定于 SequenceDiagram 的配置，可更改参与者是否镜像。因此此配置仅适用于 SequenceDiagram 类型。

   ¥Diagram-specific configurations : These are the configurations that are available and applied to a specific diagram. For each diagram there are specific configuration that will alter how that particular diagram looks and behaves. For example, mirrorActors is a configuration that is specific to the SequenceDiagram and alters whether the actors are mirrored or not. So this config is available only for the SequenceDiagram type.

注意：此处并未列出所有配置选项。要了解所有配置选项，请参阅源代码中的 defaultConfig.ts。

¥NOTE: Not all configuration options are listed here. To get hold of all the configuration options, please refer to the defaultConfig.ts in the source code.

INFO

We plan to publish a complete list of top-level configurations & diagram-specific configurations with their possible values in the docs soon.

声明指令

¥Declaring directives

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

¥Now that we have defined the types of configurations that are available, we can learn how to declare directives. A directive always starts and ends with %% signs with directive text in between, like %% {directive_text} %%.

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

¥Here the structure of a directive text is like a nested key-value pair map or a JSON object with root being init. Where all the general configurations are defined in the top level, and all the diagram specific configurations are defined one level deeper with diagram type as key/root for that section.

以下代码片段显示了指令的结构：

¥The following code snippet shows the structure of a directive:

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

你还可以在一行中定义指令，如下所示：

¥You can also define the directives in a single line, like this:

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

例如，以下代码片段：

¥For example, the following code snippet:

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

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

¥Notes: The JSON object that is passed as {argument} must be valid key value pairs and encased in quotation marks or it will be ignored. Valid Key Value pairs can be found in config.

一个简单的图表示例：

¥Example with a simple graph:

这里指令声明将为渲染的 Mermaid 图设置 logLevel 到 debug 和 theme 到 dark，从而更改图本身的外观。

¥Here the directive declaration will set the logLevel to debug and the theme to dark for a rendered mermaid diagram, changing the appearance of the diagram itself.

注意：你可以使用 'init' 或 'initialize'，因为两者都可以作为 init 指令。另请注意，%%init%% 和 %%initialize%% 指令在解析后将被分组在一起。

¥Note: You can use 'init' or 'initialize' as both are acceptable as init directives. Also note that %%init%% and %%initialize%% directives will be grouped together after they are parsed.

例如，解析上面的内容会生成下面的单个 %%init%% JSON 对象，组合两个指令并保留为 loglevel 给出的最后一个值：

¥For example, parsing the above generates a single %%init%% JSON object below, combining the two directives and carrying over the last value given for loglevel:

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

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

¥This will then be sent to mermaid.initialize(...) for rendering.

指令示例

¥Directive Examples

现在已经解释了指令的概念，让我们看一些指令用法的更多示例：

¥Now that the concept of directives has been explained, let us see some more examples of directive usage:

通过指令更改主题

¥Changing theme via directive

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

¥The following code snippet changes theme to forest:

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

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

¥Possible theme values are: default, base, dark, forest and neutral. Default Value is default.

示例：

¥Example:

通过指令更改 fontFamily

¥Changing fontFamily via directive

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

¥The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:

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

示例：

¥Example:

通过指令更改日志级别

¥Changing logLevel via directive

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

¥The following code snippet changes logLevel to 2:

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

可能的 logLevel 值为：

¥Possible logLevel values are:

• 1 用于调试，

  ¥1 for debug,

• 2 获取信息

  ¥2 for info

• 3 表示警告

  ¥3 for warn

• 4 表示错误

  ¥4 for error

• 5 仅适用于致命错误

  ¥5 for only fatal errors

默认值为 5。

¥Default Value is 5.

示例：

¥Example:

通过指令更改流程图配置

¥Changing flowchart config via directive

一些常见的流程图配置是：

¥Some common flowchart configurations are:

• htmlLabels:真假

  ¥htmlLabels: true/false

• 曲线：线性/曲线

  ¥curve: linear/curve

• 图表填充：number

  ¥diagramPadding: number

• useMaxWidth:number

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

¥For a complete list of flowchart configurations, see defaultConfig.ts in the source code. Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs.

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

¥The following code snippet changes flowchart config:

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

这里我们仅覆盖流程图配置，而不是常规配置，将 htmlLabels 设置为 true，将 curve 设置为 linear。

¥Here we are overriding only the flowchart config, and not the general config, setting htmlLabels to true and curve to linear.

通过指令更改序列图配置

¥Changing Sequence diagram config via directive

一些常见的序列图配置是：

¥Some common sequence diagram configurations are:

• width:number

• height:number

• messageAlign:左、中、右

  ¥messageAlign: left, center, right

• mirrorActors:布尔值

  ¥mirrorActors: boolean

• useMaxWidth:布尔值

  ¥useMaxWidth: boolean

• rightAngles:布尔值

  ¥rightAngles: boolean

• showSequenceNumbers:布尔值

  ¥showSequenceNumbers: boolean

• wrap:布尔值

  ¥wrap: boolean

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

¥For a complete list of sequence diagram configurations, see defaultConfig.ts in the source code. Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs.

因此，对于序列图，wrap 默认值为 false。

¥So, wrap by default has a value of false for sequence diagrams.

让我们看一个例子：

¥Let us see an example:

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

¥Now let us enable wrap for sequence diagrams.

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

¥The following code snippet changes sequence diagram config for wrap to true:

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

通过将该片段应用到上图，wrap 将被启用：

¥By applying that snippet to the diagram above, wrap will be enabled: