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

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 渲染的图表,让每张图都能携带自己的样式配置。配置共分为三个层级:配置层级说明Global Configuration(全局配置)Mermaid 的默认配置Site Configuration(站点配置)由站点所有者(site owner)制定的配置Current Configuration(当前配置)由实现者(图表作者/使用方)制定的配置向后兼容说明:旧版本 Mermaid 不会解析 directives,因为%%会把指令当作注释忽略,因此引入该机制是向后兼容的。directives 的两种形式directives 共有两种:init(或initialize)与wrap,所有指令都包裹在%%{ }%%中。secure 数组:配置修改的边界secure 数组限定了配置中可被修改的部分,它是一个不可变参数数组,站点所有者可以对其扩充,但实现者(图表作者)不能修改它。参数说明类型必填取值secure被排除在 init 指令之外的参数列表ArrayRequired任意参数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修改配置DirectiveOptionalsecure 数组之外的任意参数要点: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)函数DirectiveOptional%%{wrap}%%要点:wrap目前仅可用于序列图(sequence diagrams);它尊重手动添加的br标签——如果用户想手动控制换行位置,可以自行插入br完全掌控断行;它是一条无参数(non-argument)指令,用法为%%{wrap}%%。上方摘要后的配图即序列图中开启 wrap 后的文本换行效果;对应的换行实现依赖 utils.ts 中的文本测量与断行函数(如calculateTextDimensions、断行计算等,其中断行结果以memoize做缓存)。配置重置:reset 与 globalResetmermaidAPI上还暴露了两个仅供站点所有者调用的函数: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 Requestsecure 数组之外的任意值confsiteConfig说明:设置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 数组除外confcurrentConfig与 sanitize 后的 conf 的合并结果说明:设置currentConfig,参数conf会基于siteConfig.secure键做 sanitize——conf中凡是键名命中siteConfig.secure的值,都会被对应 siteConfig 的值替换。实现见 config.ts:它把conf作为一条“临时指令”传给updateCurrentConfig。注意源码中该函数已标注deprecated——对currentConfig的修改会在下一次addDirective或reset调用时被覆盖。getConfig函数说明类型返回值getConfig获取 currentConfigGet 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 重置为 confPut RequestRequiredNoneconf参数说明类型必填取值confcurrentConfig可被重置到的基础值集合DictionaryRequired任意值,以 secure 数组为约束说明:conf的默认值为当前siteConfig(可选,默认为getSiteConfig()的返回值)。测试如何验证 secure 边界仓库中的单元测试直接验证了本文的核心规则。config.spec.ts 中的用例should respect secure keys when applying directives设置了站点配置:const config_0: MermaidConfig { fontFamily: foo-font, securityLevel: strict, // cant be changed fontSize: 12345, // cant 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考