Mermaid TreeView 图完全指南用文本画出目录树、文件树与盒线图表【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 自 v11.14.0 起内置了 TreeView 图关键词treeView-beta用于以“目录树”形式表达层级数据文件/文件夹图标、连接线、可选的高亮与描述注释。本篇基于 docs/syntax/treeView.md 完整覆盖其语法、盒线box-drawing输入、注解系统与配置项并结合packages/mermaid/src/diagrams/treeView/下的解析器、预处理器和图标解析源码讲清每个特性背后的实现机制帮助你在文档站、README 或 Wiki 中直接嵌入可维护的文件树图。1. 基本语法缩进即层级TreeView 的结构只依赖缩进indentation。标签可以是裸标签不加引号或引号标签用于含空格的名字目录以标签末尾的/表示渲染为粗体文字图标默认隐藏——通过showIcons配置项开启内置 file/folder 图标或用icon()逐节点指定引号标签my file支持名字中带空格。最基础的示例treeView-beta my-project/ src/ index.js package.json README.md向后兼容的引号标签写法treeView-beta my project folder with spaces file.js从源码看两种标签的解析方式文法定义在 treeView.langium 中TreeNode规则先匹配可选的INDENTATION一个或多个空格/Tab再匹配QUOTED_NAME双引号或单引号或BARE_NAME。BARE_NAME的正则刻意在遇到:::、icon(、##等注解标记前停止保证裸标签与其后的注解可以分开解析。解析入口在 parser.tspopulate()中通过name.endsWith(/)判断目录并剥离尾部斜杠把节点类型标记为directory或file随后连同类名、图标、描述一起写入 DBdb.addNode(level, name, nodeType, cssClass, icon, description)。图的识别由 detector.ts 完成——只要文本以treeView-beta开头即命中随后动态加载渲染模块。之所以使用-beta后缀是因为该语法仍在按 beta 阶段演进。2. 盒线Box-Drawing输入把现成的文件树直接转成 Mermaid除了缩进你还可以用盒线字符├──、└──、│定义树结构。解析器会自动检测格式——不需要额外关键词或配置。这正是大多数文件树图在日常文档里的画法因此几乎可以零成本地把它们转成 Mermaid 图。标准├──、└──、│和加粗┣━━、┗━━、┃两套 Unicode 变体都受支持。所有注解的用法不变直接追加在标签之后深度由分支字符所在的列位置推断因此更深的嵌套天然可用注意如果发生解析错误错误信息中的行号指向你的原始输入Tab 字符会被自动展开为空格。盒线转缩进的实现机制盒线格式的底层实现是 boxDrawingPreprocessor.ts它在 Langium 解析前把盒线输入转换为等价的缩进输入格式检测isBoxDrawingFormat()扫描关键字行之后的内容行只要出现─━│┃└┗├┣中任一字符即判定为盒线格式原样输入则不做任何变换段宽推断inferSegmentWidth()找到第一个位于第 0 列之后的分支字符├/└/┣/┗其列位置即每层深度对应的段宽找不到时回退为 4深度计算对每行深度 Math.round(分支字符列位置 / 段宽) 1再转成每层 4 个空格的缩进输出行号映射预处理过程维护一个lineMap输出行号 → 原始行号解析出错时由remapErrorLines()把错误信息中的行号重映射回原始输入——这就是文档中“错误行号指向原始输入”承诺的来源健壮性细节Tab 会先被统一替换为 4 个空格以保证列计算一致纯装饰行只有│和空白会被跳过若盒线格式中混入“有缩进但无分支字符”的行会抛出明确的错误提示引导改用├──/└──前缀。单元测试位于 boxDrawingPreprocessor.spec.ts可对照验证上述行为。3. 注解系统高亮、描述与图标注解在 treeView.langium 中是三个独立的终端terminalCLASS_ANNOTATION:::类名、ICON_ANNOTATIONicon(...)、DESC_ANNOTATION## ...每个节点可任意组合多个。3.1 用 :::class 高亮给节点追加:::className应用 CSS 类其中内置了highlight类treeView-beta src/ App.tsx :::highlight index.js package.json高亮的背景色与描边色由主题变量highlightBg/highlightStroke控制见第 6 节主题变量表。3.2 用 ## 添加行内描述在##后追加可见描述会以斜体渲染在标签旁边treeView-beta src/ index.js ## app entry point config.ts ## runtime configuration package.json ## project manifest描述文本在 parser.ts 中会经过sanitizeText()消毒防止 HTML 注入。3.3 图标图标默认隐藏。将showIcons设为true即可显示内置图标——文件为file、目录为folder--- config: treeView: showIcons: true --- treeView-beta src/ index.js package.json通过配置映射实现文件类型图标Mermaid不自带文件名/扩展名映射——文件类型图标完全由用户通过filenameIcons与extensionIcons配置项定义可引用已注册图标包如 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()可以看到匹配优先级精确文件名匹配优先于扩展名匹配扩展名比较不区分大小写且带点与不带点的键.ts与ts都接受。用 icon() 显式覆盖图标用icon(name)显式指定某节点的图标name为已注册图标包中的任意图标按pack:name引用。显式图标总是渲染即使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 的getNodeIcon()中优先级为icon(none)→ 不渲染显式icon()注解 → 经qualifyIcon()补全前缀后渲染showIcons为关 → 不渲染showIcons为开且是文件 → 查filenameIcons/extensionIcons映射未命中回退内置file图标目录回退内置folder图标。注意图标包不随 Mermaid 一起打包——必须由嵌入图标的站点调用registerIconPacks注册参见图标包注册。未注册的图标会渲染为一个问号。隐藏单个节点的图标当showIcons开启时用icon()或icon(none)隐藏单个节点的图标--- config: treeView: showIcons: true --- treeView-beta src/ index.js icon(none) package.json3.4 组合注解各类注解可以任意顺序组合treeView-beta my-project/ src/ App.tsx :::highlight icon(logos:react) ## main component index.js ## entry point .env ## environment variables Dockerfile package.json4. 注释使用%%写不可见注释Mermaid 通用约定treeView-beta %% Generated files — do not edit src/ generated/ index.js在盒线格式中%%开头的行会被预处理器原样透传见 boxDrawingPreprocessor.ts由 Langium 的ML_COMMENT隐藏终端消化。5. 更多示例带引号标签的基础示例treeView-beta packages mermaid src parserUnicode 与 emoji 标签标签按原文渲染——Unicode 字符与连续空格都会保留。由于内置图标默认隐藏emoji 是很方便的“内联图标”treeView-beta rocket-app/ packages/ ui/ ️ utils/ tests/ README.md ⚙️ config.yaml自定义配置示例行距、线宽、字号与颜色--- config: treeView: rowIndent: 80 lineThickness: 3 themeVariables: treeView: labelFontSize: 20px labelColor: #FF0000 lineColor: #00FF00 --- treeView-beta packages mermaid src parser仓库中还提供了可运行的演示页 demos/treeView.html 与示例定义 tree-view.ts以及一组端到端快照用例e2e/diagrams/tree-view/ 下的.mmd文件覆盖裸标签、引号标签、多根节点、图标覆盖、未注册图标回退等场景可作为各特性正确渲染的对照基准。6. 配置项与主题变量配置项config以下默认值与 docs/syntax/treeView.md 的配置表一致并可在 config.type.ts 的TreeViewDiagramConfig接口中逐项查证属性说明默认值rowIndent每行每个层级差的缩进距离10paddingX行的水平内边距5paddingY行的垂直内边距5lineThickness连接线粗细1showIcons是否显示默认 file/folder 图标显式icon()总是渲染falsedefaultIconPack用于解析无前缀图标引用的已注册 iconify 图标包filenameIcons文件名 → 图标 映射文件类型图标{}extensionIcons扩展名 → 图标 映射文件类型图标{}主题变量themeVariables.treeView属性说明默认值labelFontSize标签字号16pxlabelColor标签颜色blacklineColor连接线颜色blackiconColor图标颜色作用于使用currentColor的图标#546e7adescriptionColor##描述文本颜色#6a9955highlightBg高亮背景填充rgba(255,193,7,0.15)highlightStroke高亮边框描边#ffc107iconColor生效的原理内置file/folder图标的 SVG 路径使用fillcurrentColor见 icons.ts 中的treeViewIcons定义因此只要 CSScolor改变即该主题变量图标颜色随之变化。7. 小结TreeView 图的核心设计可以概括为三层输入层缩进或盒线两种等价输入由 boxDrawingPreprocessor.ts 自动归一化行号可回溯到原始输入语义层treeView.langium 文法把裸/引号标签与:::class、icon()、##注解解析为结构化 AST目录由尾斜杠判定表现层rowIndent等 8 个配置项控制几何7 个主题变量控制颜色与字体图标解析遵循“显式icon() 配置映射 内置图标”的清晰优先级。这使得 TreeView 既能手绘简洁的目录树也能把现成的盒线文件树原样粘进 Mermaid 代码块再用少量注解完成高亮、说明与图标定制。【免费下载链接】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），仅供参考