企业官网建设流程全解析

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

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

本文基于 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 渲染的图表,让每张图都能携带自己的样式配置。

配置共分为三个层级:

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

directives 的两种形式

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

secure 数组:配置修改的边界

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

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是参数型指令(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目前仅可用于序列图(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

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

getSiteConfig

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

setConfig

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

getConfig

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

sanitize

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

reset 与 conf 参数

说明: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 文档。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid