Mermaid 8.6.0 配置体系详解:directives 指令、secure 数组与新版配置 API

本文基于 Mermaid 仓库中记录的 Version 8.6.0 变更文档(源文件位于 8.6.0_docs.md,由 packages/mermaid/src/docs/config/8.6.0_docs.md 自动生成),系统讲解 8.6.0 版本引入的配置新体系:init/wrap 两条 directives 指令、三层配置模型(Global/Site/Current)、secure 数组安全边界、reset/globalReset 重置机制,以及 setSiteConfig、sanitize 等 8.6.0 新增 API。读完后,你能掌握在网页中安全地、按层级定制图表外观的方法,并能对照 config.ts 源码验证每条配置规则的底层实现。

序列表图中使用 wrap 指令实现文本自动换行的效果

8.6.0 引入 directives:配置的“一次性覆写”机制

8.6.0 版本带来了 Mermaid directives(指令)体系,这是一套用于修改配置的新系统,目标是建立集中、合理的默认值与简单的实现方式。

其核心语义是:

• directives 允许对 config 进行一次性(single-use)覆写,正如 配置文档 中所讨论的那样;
• 它允许站点上的图表作者(Diagram Authors)通过 Directives 对 config 做临时修改——指令在图表定义被渲染之前被解析,从而改变图表的外观;
• init 指令是 Site 层与 Current 层配置的主要手段;
• 一个典型应用场景是:在公司/组织网页中嵌入依赖 Mermaid 渲染的图表,让每张图都能携带自己的样式配置。

配置共分为三个层级:

配置层级	说明
Global Configuration(全局配置)	Mermaid 的默认配置
Site Configuration(站点配置)	由站点所有者(site owner)制定的配置
Current Configuration(当前配置)	由实现者(图表作者/使用方)制定的配置

向后兼容说明:旧版本 Mermaid 不会解析 directives,因为 %% 会把指令当作注释忽略,因此引入该机制是向后兼容的。

directives 的两种形式

directives 共有两种:init(或 initialize)与 wrap,所有指令都包裹在 %%{ }%% 中。

secure 数组:配置修改的边界

secure 数组 限定了配置中可被修改的部分,它是一个不可变参数数组,站点所有者可以对其扩充,但实现者(图表作者)不能修改它。

参数	说明	类型	必填	取值
secure	被排除在 init 指令之外的参数列表	Array	Required	任意参数

secure 数组的工作方式类似“套娃”(nesting dolls):Global 配置的 secure 数组保存了默认且不可变的参数列表(最小的那只娃娃),站点所有者可以在其上追加,但实现者无权修改。

站点所有者可以用如下方式扩充 secure 数组:

mermaidAPI.initialize( { startOnLoad: true, secure: ['parameter1', 'parameter2'] } );

文档中列出的 secure 数组默认值包括:['secure', 'securityLevel', 'startOnLoad', 'maxTextSize'],这些默认值不可变。实现者只能通过 directives 修改配置,且无法改动 secure 数组本身。

源码印证:在 config.ts 的 sanitize 函数中可以看到这一边界的强制实现——它会遍历 ['secure', ...(siteConfig.secure ?? [])],凡命中 secure 键的选项一律 delete 并记录 Denied attempt to modify a secure key;此外还会移除所有以 __ 开头的键以防原型污染,并递归删除字符串值中出现的 <、> 与 url(data: 以防 XSS。这正对应文档所说的“init 传入的配置不能修改更高层级 secure 数组中的参数,发生冲突时 secure 数组优先,解析照常进行但不改变冲突参数”。同时,这些被保护参数的语义在 config.schema.yaml 中有完整描述,例如 securityLevel(取值 strict/loose/antiscript/sandbox)与 maxTextSize(默认 50000)。

init 指令:覆写任意非 secure 参数

init(或 initialize)指令允许用户覆写并修改所有未列入 secure 数组的配置参数。

参数	说明	类型	必填	取值
init	修改配置	Directive	Optional	secure 数组之外的任意参数

要点:

• init 是参数型指令(argument-directive),格式为 %%{init: { **参数写在这里**}}%%;
• 作为 {**argument**} 传入的 JSON 对象必须是合法且带引号的 JSON,否则会被忽略;
• 通过 init 传入的配置不能修改高层级 secure 数组中的参数;发生冲突时,Mermaid 优先采用 secure 数组,并照常解析请求,但不改变冲突参数的取值;
• 在代码中部署时,init 需要写在图/图表描述之前。

示例:

%%{init: {"theme": "default", "logLevel": 1 }}%%
graph LR
  a-->b
  b-->c
  c-->d
  d-->e
  e-->f
  f-->g
  g-->

源码印证:config.ts 中的 addDirective 是 directives 的入口——它先调用 sanitizeDirective 校验指令,再处理 fontFamily 到 themeVariables 的映射,最后把指令压入 directives 数组并触发 updateCurrentConfig。后者(见 config.ts)的合并顺序清晰体现了三层模型:以 siteConfig 为基底,逐条应用(已 sanitize 的)指令,若指令中指定了主题,还会用 themeVariables 重新计算主题变量。

wrap 指令:序列图文本换行

参数	说明	类型	必填	取值
wrap	一个可调用的文本换行(text-wrap)函数	Directive	Optional	%%{wrap}%%

要点:

• wrap 目前仅可用于序列图(sequence diagrams);
• 它尊重手动添加的 <br> 标签——如果用户想手动控制换行位置,可以自行插入 <br> 完全掌控断行;
• 它是一条无参数(non-argument)指令,用法为 %%{wrap}%%。

上方摘要后的配图即序列图中开启 wrap 后的文本换行效果;对应的换行实现依赖 utils.ts 中的文本测量与断行函数(如 calculateTextDimensions、断行计算等,其中断行结果以 memoize 做缓存)。

配置重置:reset 与 globalReset

mermaidAPI 上还暴露了两个仅供站点所有者调用的函数:

• reset:把配置重置回“上一次”的配置状态,用于撤销自上次 mermaidAPI.initialize({...}) 之后的较新改动;
• globalReset:把当前配置和站点配置一并重置回全局默认值。

注意:两者都只对站点所有者可用;实现者只能通过 init 指令来调整自己的配置。

源码印证:在 mermaidAPI.ts 中可以看到这两个 API 的实际绑定:

reset: () => {
  configApi.reset();
},
globalReset: () => {
  configApi.reset(configApi.defaultConfig);
},

即 reset() 等价于把 currentConfig 重置为 siteConfig,而 globalReset() 等价于以 defaultConfig 为基准重置,与文档中“reset 回到 siteConfig、传入 defaultConfig 则 siteConfig 与 currentConfig 一并回到默认”的描述一致。configApi.reset 的实现在 config.ts:清空 directives 数组,再以给定配置(默认 siteConfig)重建 currentConfig。

8.6.0 附带的工具函数

文档还记录了 8.6.0 为 Mermaid 新增的三个工具:

• memoize:为计算密集型函数提供简单缓存,文档称其将渲染时间减少约 90%。在 utils.ts 中,memoize 被用于缓存文本测量(如 calculateTextDimensions)与断行计算等结果;
• assignWithDepth:对早期 config.js 与 Object.assign 的改进,提供“带深度”的合理对象合并机制,类似 object.assign 但递归合并嵌套对象。独立实现在 assignWithDepth.ts,并被 config.ts 用于构建 defaultConfig、siteConfig 与 currentConfig 的深拷贝,这正是三层配置互不污染的关键;
• calculateTextDimensions、calculateTextWidth 与 calculateTextHeight:用于测量文本的尺寸、宽度与高度,定义于 utils.ts。更多用法、参数与返回值信息可查阅 utils 包中这些函数的 jsdoc。

下图分别展示了 assignWithDepth 的带深度合并效果,以及与不带深度的 object.assign 的对比:

object.assign 不带深度合并的对比效果

8.6.0 引入的新 API 一览

以下各函数的实现集中在 config.ts,并经 mermaidAPI 对外导出。

setSiteConfig

函数	说明	类型	取值	参数	返回值
setSiteConfig	将 siteConfig 设置为期望值	Put Request	secure 数组之外的任意值	conf	siteConfig

说明:设置 siteConfig。siteConfig 是受保护的、用于重复使用的配置;调用 reset() 会把 currentConfig 重置回 siteConfig,调用 reset(configApi.defaultConfig) 则会把 siteConfig 与 currentConfig 一并重置回 defaultConfig;该函数内部会同时设置 currentConfig;默认值镜像 Global Config。源码实现见 config.ts:先以 defaultConfig 为基底深拷贝,再并入传入的 conf(含主题变量计算),最后调用 updateCurrentConfig 同步 currentConfig。

getSiteConfig

函数	说明	类型	返回值
getSiteConfig	返回当前的 siteConfig 基础配置	Get Request	返回 siteConfig 中的任意值

说明:返回 siteConfig 中的任意值。实现见 config.ts,返回的是 siteConfig 的深拷贝,避免外部直接改写内部状态。

setConfig

函数	说明	类型	取值	参数	返回值
setConfig	将 currentConfig 设置为期望值	Put Request	任意值,secure 数组除外	conf	currentConfig 与 sanitize 后的 conf 的合并结果

说明:设置 currentConfig,参数 conf 会基于 siteConfig.secure 键做 sanitize——conf 中凡是键名命中 siteConfig.secure 的值,都会被对应 siteConfig 的值替换。实现见 config.ts:它把 conf 作为一条“临时指令”传给 updateCurrentConfig。注意源码中该函数已标注 @deprecated——对 currentConfig 的修改会在下一次 addDirective 或 reset 调用时被覆盖。

getConfig

函数	说明	类型	返回值
getConfig	获取 currentConfig	Get Request	返回 currentConfig 中的任意值

说明:返回 currentConfig 中的任意值。实现见 config.ts,同样返回深拷贝;jsdoc 建议避免反复调用,而应将结果存入变量复用。

sanitize

函数	说明	类型	取值
sanitize	确保 options 不试图覆写 siteConfig 的 secure 键	Put Request(?)	None

说明:就地(in-place)修改 options 参数,确保其不覆写 siteConfig 的 secure 键。实现细节见前文 secure 数组一节的 config.ts。

reset 与 conf 参数

函数	说明	类型	必填	取值	参数
reset	将 currentConfig 重置为 conf	Put Request	Required	None	conf

参数	说明	类型	必填	取值
conf	currentConfig 可被重置到的基础值集合	Dictionary	Required	任意值,以 secure 数组为约束

说明:conf 的默认值为当前 siteConfig(可选,默认为 getSiteConfig() 的返回值)。

测试如何验证 secure 边界

仓库中的单元测试直接验证了本文的核心规则。config.spec.ts 中的用例 should respect secure keys when applying directives 设置了站点配置:

const config_0: MermaidConfig = {
  fontFamily: 'foo-font',
  securityLevel: 'strict', // can't be changed
  fontSize: 12345, // can't be changed
  secure: [...configApi.defaultConfig.secure!, 'fontSize'],
};
configApi.setSiteConfig(config_0);

随后注入 fontFamily: 'baf'、篡改 fontSize 与 securityLevel 的指令,验证只有非 secure 键(fontFamily)生效——这正是“secure 数组冲突时优先”规则的自动化证明。

小结与延伸阅读

8.6.0 建立的三层配置模型(Global → Site → Current)加 secure 数组边界,让“站点统管安全与默认值、图表作者按图定制外观”成为可能:实现者用 %%{init: {...}}%% 做一次性覆写,站点所有者用 initialize/setSiteConfig 扩充 secure 数组并以 reset/globalReset 收回控制权。所有规则均可在 config.ts、mermaidAPI.ts 与 config.spec.ts 中逐一对照验证。更多完整的配置与指令用法,请阅读 Setup 文档、configuration 文档 与 directives 文档。