企业官网建设流程全解析

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 自 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.ts：populate()中通过name.endsWith('/')判断目录并剥离尾部斜杠，把节点类型标记为directory或file，随后连同类名、图标、描述一起写入 DB（db.addNode(level, name, nodeType, cssClass, icon, description)）。

图的识别由 detector.ts 完成——只要文本以treeView-beta开头即命中，随后动态加载渲染模块。之所以使用-beta后缀，是因为该语法仍在按 beta 阶段演进。

2. 盒线（Box-Drawing）输入：把现成的文件树直接转成 Mermaid

除了缩进，你还可以用盒线字符（├──、└──、│）定义树结构。解析器会自动检测格式——不需要额外关键词或配置。这正是大多数文件树图在日常文档里的画法，因此几乎可以零成本地把它们转成 Mermaid 图。标准（├──、└──、│）和加粗（┣━━、┗━━、┃）两套 Unicode 变体都受支持。

所有注解的用法不变，直接追加在标签之后：

深度由分支字符所在的列位置推断，因此更深的嵌套天然可用：

注意：如果发生解析错误，错误信息中的行号指向你的原始输入；Tab 字符会被自动展开为空格。

盒线转缩进的实现机制

盒线格式的底层实现是 boxDrawingPreprocessor.ts，它在 Langium 解析前把盒线输入转换为等价的缩进输入：

1. 格式检测：isBoxDrawingFormat()扫描关键字行之后的内容行，只要出现─━│┃└┗├┣中任一字符即判定为盒线格式，原样输入则不做任何变换；
2. 段宽推断：inferSegmentWidth()找到第一个位于第 0 列之后的分支字符（├/└/┣/┗），其列位置即每层深度对应的段宽，找不到时回退为 4；
3. 深度计算：对每行，深度 =Math.round(分支字符列位置 / 段宽) + 1，再转成每层 4 个空格的缩进输出；
4. 行号映射：预处理过程维护一个lineMap（输出行号 → 原始行号），解析出错时由remapErrorLines()把错误信息中的行号重映射回原始输入——这就是文档中“错误行号指向原始输入”承诺的来源；
5. 健壮性细节：Tab 会先被统一替换为 4 个空格以保证列计算一致；纯装饰行（只有│和空白）会被跳过；若盒线格式中混入“有缩进但无分支字符”的行，会抛出明确的错误提示，引导改用├──/└──前缀。

单元测试位于 boxDrawingPreprocessor.spec.ts，可对照验证上述行为。

3. 注解系统：高亮、描述与图标

注解在 treeView.langium 中是三个独立的终端（terminal）：CLASS_ANNOTATION（:::类名）、ICON_ANNOTATION（icon(...)）、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()中，优先级为：

1. icon(none)→ 不渲染；
2. 显式icon()注解 → 经qualifyIcon()补全前缀后渲染；
3. showIcons为关 → 不渲染；
4. showIcons为开且是文件 → 查filenameIcons/extensionIcons映射，未命中回退内置file图标，目录回退内置folder图标。

注意：图标包不随 Mermaid 一起打包——必须由嵌入图标的站点调用registerIconPacks注册（参见图标包注册）。未注册的图标会渲染为一个问号。

隐藏单个节点的图标

当showIcons开启时，用icon()或icon(none)隐藏单个节点的图标：

--- config: treeView: showIcons: true --- treeView-beta src/ index.js icon(none) package.json

3.4 组合注解

各类注解可以任意顺序组合：

treeView-beta my-project/ src/ App.tsx :::highlight icon(logos:react) ## main component index.js ## entry point .env ## environment variables Dockerfile package.json

4. 注释

使用%%写不可见注释（Mermaid 通用约定）：

treeView-beta %% Generated files — do not edit src/ generated/ index.js

在盒线格式中，%%开头的行会被预处理器原样透传（见 boxDrawingPreprocessor.ts），由 Langium 的ML_COMMENT隐藏终端消化。

5. 更多示例

带引号标签的基础示例：

treeView-beta "packages" "mermaid" "src" "parser"

Unicode 与 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接口中逐项查证：

主题变量（themeVariables.treeView）

iconColor生效的原理：内置file/folder图标的 SVG 路径使用fill="currentColor"（见 icons.ts 中的treeViewIcons定义），因此只要 CSScolor改变（即该主题变量），图标颜色随之变化。

7. 小结

TreeView 图的核心设计可以概括为三层：

1. 输入层：缩进或盒线两种等价输入，由 boxDrawingPreprocessor.ts 自动归一化，行号可回溯到原始输入；
2. 语义层：treeView.langium 文法把裸/引号标签与:::class、icon()、##注解解析为结构化 AST，目录由尾斜杠判定；
3. 表现层：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