Mermaid TreeView 树状视图图解指南语法、配置与源码实现【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid导读本文聚焦 Mermaid 仓库中相对较新的TreeView树状视图图它用于以目录树的形式表达层级化数据支持文件/文件夹图标、连接线与可选注释。文中将完整梳理该图的缩进语法、treeView-beta关键字、box-drawing制表符风格输入、三类节点注释:::class、##描述、icon()与全部配置项并结合 packages/mermaid/src/diagrams/treeView 下的解析器、预处理器、数据层、渲染器源码揭示其底层工作机制。读完本文你将掌握如何把一个常见的文件树文本零改造转成 Mermaid TreeView 图并能通过配置实现图标、高亮、描述与主题定制。TreeView 图的定位与适用场景TreeView 图用于以目录式结构表达层级数据节点带文件/文件夹图标、连接线以及可选的注解。根据 syntax/treeView.md 顶部标注该能力自 v11.14.0 起可用图类型关键字目前写作treeView-beta。典型的应用场景包括展示项目目录结构、表达嵌套配置层级、绘制依赖/包关系树等。其核心设计目标是让“用缩进书写的目录树文本”能够零成本变为可视化 SVG这是与 flowchart/classDiagram 等图最大的差异点结构完全由缩进决定而不是由连线语句决定。从注册机制看TreeView 是一个“外部扩展图”在 detector.ts 中通过正则/^\s*treeView-beta/识别文本开头一旦命中便通过懒加载引入 diagram.ts 中注册的db数据层、renderer渲染器、parser解析器与styles样式表。这意味着任何以treeView-beta开头的代码块都会被 Mermaid 识别为 TreeView 图。基本语法以缩进构建层级三条核心规则TreeView 的结构只依赖缩进。在 parser.ts 中节点类型由解析器判定为directory或file。文档明确了三条规则目录以末尾/标识标签以/结尾时判定为目录渲染为粗体文字图标默认隐藏可通过showIcons配置开启内置文件/文件夹图标或用icon()为单个节点指定图标带引号的标签my file可以包含空格。最小示例无mermaid-example围栏纯文本结构示意treeView-beta my-project/ src/ index.js package.json README.md带引号标签向后兼容的写法用于含空格的名称treeView-beta my project folder with spaces file.js缩进层级在解析后被送入数据层。查看 db.ts 可以发现一个实现细节数据层维护一个“虚拟根节点”name: /level: -1每当新节点的层级level 栈顶节点.level时不断弹栈直到找到正确的父节点再将该节点挂为栈顶的子节点并压栈。getRoot()返回的这颗树即渲染器的输入。目录判断的源码印证在 parser.ts 中可以看到目录判定逻辑先判断标签是否以/结尾name.endsWith(/)若是目录则name name.slice(0, -1)即渲染时/不显示而是通过样式类treeView-node-dir以粗体呈现——对应 styles.ts 中的font-weight: bold。Box-Drawing制表符输入自动识别零成本迁移除缩进外TreeView 还支持使用 Unicode box-drawing 字符定义结构解析器自动检测格式无需额外关键字或配置。这意味着日常文件树工具导出的文本可直接转成 Mermaid 图。支持两套变体标准变体├──、└──、│粗体变体┣━━、┗━━、┃。treeView-beta ├── src/ │ ├── index.ts │ └── utils.ts ├── package.json └── README.md所有注释highlight、图标、描述在 box-drawing 模式下用法完全相同只需附加在标签之后treeView-beta ├── src/ │ ├── App.tsx :::highlight icon(logos:react) ## main component │ └── index.ts ## entry point ├── .env ## environment variables ├── Dockerfile └── package.json深度由分支字符├/└/┣/┗所在的列位置推断因此深层嵌套天然可用treeView-beta ├── packages/ │ ├── mermaid/ │ │ ├── src/ │ │ │ ├── parser.ts │ │ │ └── renderer.ts │ │ └── package.json │ └── parser/ │ └── src/ └── README.mdNote:若发生解析错误错误信息中的行号指向你的原始输入。Tab 字符会被自动展开为空格。底层实现boxDrawingPreprocessor这一能力并非语法langium本身支持而是由一个预处理器完成。查看 boxDrawingPreprocessor.ts 的实现先用字符类正则ALL_BOX_CHARS /[─━│┃└┗├┣]/检测文本是否含 box-drawing 字符在找到treeView-beta关键字之后通过首个非 0 列的分支字符位置推断每段宽度segmentWidth推断失败时回退为 4每个节点深度按Math.round(branchCol / segmentWidth) 1计算最终把 box-drawing 文本转换为每层 4 个空格的缩进格式再交给 langium 解析同时在 parser.ts 中维护了输出行号到原始行号的映射出错时调用remapErrorLines把报错行号回映到用户原始文本这正是上面 Note 中“行号指向原始输入”的由来。一个值得注意的边界规则若在 box-drawing 模式下出现没有框线字符的前导空格预处理器会抛出“Unexpected indentation without box-drawing characters”错误提示混用格式必须使用├──/└──前缀。因此实际使用时不要在同一张图中混用“缩进”与“box-drawing”两种风格。节点注释Annotations用:::class高亮为节点附加:::className即可应用 CSS 类。内置提供highlight类将节点以带背景色/描边的高亮框显示treeView-beta src/ App.tsx :::highlight index.js package.json从渲染器源码看renderer.ts 会检测cssClass是否包含highlight若是则在节点组最底层插入一个带treeView-highlight-bg类的矩形其圆角半径rx3之后在第三阶段把矩形宽度扩展到整棵树的宽度见drawTree的 Phase 3从而形成贯通整行的醒目高亮条。用##添加行内描述在标签后写## description即可显示一段斜体说明文字渲染于标签右侧treeView-beta src/ index.js ## app entry point config.ts ## runtime configuration package.json ## project manifest渲染细节描述文字使用treeView-node-description样式类在 styles.ts 中font-style: italic、颜色由descriptionColor决定并在drawTree的第二阶段统一对齐到所有标签中最右边界 DESC_GAP(16)的公共列因此多行描述会整齐地左对齐在同一竖线上。图标系统图标默认隐藏。将配置项showIcons设为true即可开启内置图标——文件用file、目录用folder--- config: treeView: showIcons: true --- treeView-beta src/ index.js package.jsonMermaid 源码中内置图标包定义在 icons.ts图标集前缀为mermaid-treeview仅包含file与folder两个原始绘制的图标均使用currentColor因此可随 CSScolor主题化。文件类型图标filenameIcons与extensionIconsMermaid不内置文件名/扩展名映射——文件类型图标完全由用户通过配置定义图标取自已注册的 icon pack参见 注册图标包指南如 material-icon-theme。配置值按icon()的解析规则处理pack:name原样使用无前缀的名字经由defaultIconPack解析none则隐藏匹配文件的图标。目录和未映射到的文件保持内置的folder/file图标。--- config: treeView: showIcons: true defaultIconPack: material-icon-theme filenameIcons: Dockerfile: docker extensionIcons: .ts: typescript .tsx: react-ts .txt: none --- treeView-beta src/ App.tsx utils.ts Dockerfile notes.txt README.md配置如何生效可由 icons.ts 的detectIcon()印证文件名匹配优先于扩展名匹配先查filenameIcons[name]扩展名查找时键大小写不敏感内部统一转小写且带不带前导点均可命中先查.ts再查ts——所以配置里写.ts与ts效果一致未命中任何映射的文件回退到内置file图标。单节点图标覆盖icon(name)用icon(name)显式指定某节点的图标name可以是已注册 icon pack见 注册图标包指南中的任意图标以pack:name形式引用。显式icon()始终渲染即使showIcons关闭也有效treeView-beta src/ App.tsx icon(logos:react) index.js package.json当设置了defaultIconPack后无前缀名字会经由该包解析——icon(rust)相当于icon(material-icon-theme:rust)的简写。内置file/folder图标则永远可以不带前缀直接引用如icon(folder)。这一“限定规则”在 icons.ts 的qualifyIcon()中实现含:的名字直接用否则若是内置图标或未设置defaultIconPack则落到mermaid-treeview前缀否则才拼上defaultIconPack。Icon packs 不随 Mermaid 打包——必须由嵌入图标的网站调用 registerIconPacks 进行注册详见 [注册图标包指南](https://link.gitcode.com/i/6dd67b0d9a11a709c6c986f8cc27a8e0)。未注册的图标会渲染为问号。这一点与渲染链路吻合TreeView 渲染器 renderer.ts 会先注册自带treeViewIcons包而用户在宿主侧通过registerIconPacks注册其他 Iconify 包如 material-icon-theme。图标大小为ICON_SIZE 14与标签之间留ICON_GAP 4的空隙。e2e 测试中should-render-the-unknown-icon-fallback-for-unregistered-icons.mmd见 e2e/diagrams/tree-view正是验证该回退行为。隐藏图标当showIcons开启时可用icon()或icon(none)隐藏单个节点的图标--- config: treeView: showIcons: true --- treeView-beta src/ index.js icon(none) package.json这在 icons.ts 的getNodeIcon()中有清晰的优先级说明none最高优先级直接返回“不渲染”其次显式icon()注释仅当showIcons打开时才匹配用户配置的 filename/extension 映射最后兜底返回内置 file/folder。同时 e2e/diagrams/tree-view/should-hide-default-icons-with-icon-none-and-icon.mmd 对这一场景做了快照验证。组合注释所有注释可以任意顺序组合treeView-beta my-project/ src/ App.tsx :::highlight icon(logos:react) ## main component index.js ## entry point .env ## environment variables Dockerfile package.json从解析端看parser.ts 分别从 AST 中读取classAnnotation、iconAnnotation、descAnnotation三个独立字段因此:::class、icon()、## desc之间互不干扰、顺序无关。对应 e2e 用例 e2e/diagrams/tree-view/should-render-combined-annotations.mmd。注释行Comments用%%写不可见注释沿用 Mermaid 通用约定treeView-beta %% Generated files — do not edit src/ generated/ index.js预处理器 boxDrawingPreprocessor.ts 对注释行一律原样透传不会参与层级推断因此注释可以出现在任意位置。综合示例带引号标签的基础示例treeView-beta packages mermaid src parser标签中的 Unicode 与 emoji标签按书写原样渲染——Unicode 字符与连续空格都会被保留样式表.treeView-node-label中设置了white-space: pre。由于内置图标默认隐藏emoji 恰好可以作为顺手可用的“行内图标”treeView-beta rocket-app/ packages/ ui/ ️ utils/ tests/ README.md ⚙️ config.yamle2e 测试 e2e/diagrams/tree-view/should-preserve-consecutive-spaces-and-unicode-in-labels.mmd 与should-render-emoji-as-icons-with-the-default-icons-hidden.mmd专门覆盖了这类标签。自定义配置示例--- config: treeView: rowIndent: 80 lineThickness: 3 themeVariables: treeView: labelFontSize: 20px labelColor: #FF0000 lineColor: #00FF00 --- treeView-beta packages mermaid src parser配置变量Config VariablesTreeView 的配置项挂在treeView命名空间下完整的配置合并逻辑见 db.tscleanAndMerge将默认配置与运行时用户配置深度合并默认值来源可回溯到 defaultConfig.ts 的treeView节。Property描述默认值rowIndent每一行每一层深度的缩进量10paddingX行的水平内边距5paddingY行的垂直内边距5lineThickness连接线的粗细1showIcons是否显示默认的文件/文件夹图标显式icon()始终渲染falsedefaultIconPack用于解析无前缀图标引用的已注册 Iconify packfilenameIcons“文件名 → 图标”映射用于文件类型图标{}extensionIcons“扩展名 → 图标”映射用于文件类型图标{}几个参数在渲染器 renderer.ts 中的实际影响值得说明每个节点的水平缩进计算为depth * (config.rowIndent config.paddingX)drawNode连接线水平段从indent - config.rowIndent画到indent因此rowIndent同时决定“层间间隔”与“短线长度”行的宽高由标签 bbox 加上 2 倍paddingX/paddingY得出lineThickness直接作用于所有line的stroke-width并且在最终viewBox计算时左侧额外预留了lineThickness / 2的空间见 renderer 中的注释坐标为 0 的线居中绘制时会向左溢出半个线宽useMaxWidth同样在 TreeView 中被配置见 defaultConfig.ts用于决定 SVG 是否按最大宽度自适应。主题变量Theme Variables主题变量位于themeVariables.treeView下供各主题统一换肤。样式默认值定义在 styles.ts并通过cleanAndMerge与主题注入值合并后生成对应 CSSProperty描述默认值labelFontSize标签字体大小16pxlabelColor标签颜色blacklineColor连接线颜色blackiconColor图标颜色作用于使用currentColor的图标#546e7adescriptionColor##描述文字的颜色#6a9955highlightBg高亮背景填充色rgba(255,193,7,0.15)highlightStroke高亮边框描边色#ffc107小结与进一步探索TreeView 把“文件树文本 → 结构化层级图”的体验做到了近乎零门槛缩进或 box-drawing 两种书写方式都会被自动解析:::highlight、##、icon()三类注释解决了表达重点而showIcons 用户自定义 filename/extension 映射则补全了文件类型图标诉求。建议进一步阅读仓库内资源以加深理解完整规格文档docs/syntax/treeView.md源码实现目录packages/mermaid/src/diagrams/treeViewdetector.ts→parser.ts→db.ts→renderer.ts→styles.ts的标准扩展图链路box-drawing 预处理器核心boxDrawingPreprocessor.ts含格式检测、段宽推断、行号回映三块逻辑图标解析优先级icons.ts端到端快照用例e2e/diagrams/tree-view15 个.mmd场景覆盖引用标签、高亮、描述、emoji、图标覆盖与 fallback 等图标包注册规范docs/config/icons.md。【免费下载链接】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），仅供参考