Mermaid Visual Editor 应该何时使用可视化编辑器或文本编辑器？

Mermaid Visual Editor 与文本编辑器始终可用并保持同步，选择标准不是“会不会写代码”，而是哪种方式更快、更可控。搭建初始结构、拖拽连线、改形状颜色时优先可视化编辑器；精确修改语法、连接逻辑、子图或复杂流程时优先文本编辑器。

两种编辑器的核心区别

任务	优先使用	原因
快速画出第一版结构	可视化编辑器	通过点击和拖拽即可建立节点与连线
改变节点形状或颜色	可视化编辑器	能直接看到样式结果
快速连接多个节点	可视化编辑器	拖拽关系比手写 ID 更直观
修改一条确定的边	文本编辑器	起点、终点和标签表达精确
处理子图和复杂流程	文本编辑器	层级与依赖更容易审查
批量改名或统一代码	文本编辑器	适合搜索、替换和差异比较
要求保留源码原始排版	文本编辑器	可视化编辑会自动格式化代码

官方文档明确说明，两种编辑器的变更会相互反映。实际工作不必固定只用一种，可以在画布中构思、在代码中精修，再回画布验收。

什么时候优先使用可视化编辑器

当任务还处于探索阶段，节点名称和关系尚未完全确定时，可视化编辑器更合适。它能让用户先看到整体结构，再逐步补充细节。

• 从空白画布快速搭建流程骨架。
• 试验横向、纵向或层次布局。
• 为决策、数据库、文档等语义选择形状。
• 通过颜色区分状态或节点类别。
• 把已有节点拖入子图形成分组。
• 与不熟悉 Mermaid 语法的同事共同评审。

可视化编辑器适合回答“图应该长什么样”和“关系是否直观”，尤其适合流程图的初稿。

什么时候优先使用文本编辑器

当目标已经明确，修改范围可以精确描述时，文本编辑器通常更高效。

• 修正节点 ID、箭头方向或边标签。
• 建立嵌套子图和复杂连接。
• 处理循环、条件分支和多条并行路径。
• 批量复制相似结构。
• 检查代码差异并纳入版本控制。
• 保留团队约定的缩进、换行和注释格式。

文本编辑器适合回答“图的逻辑是否精确”和“这次到底改了什么”。

保留源码格式时只能用文本编辑器

这是两种方式之间最容易忽略的边界。当前官方文档说明，Visual Editor 在生成变更时会美化并重构代码格式。图表语义可能不变，但缩进、换行或声明顺序可能变化。

如果 Mermaid 源码需要保持极小差异，例如代码评审只允许修改一条边，或者文件包含团队固定排版，应在该次任务中只使用文本编辑器。否则一次视觉操作可能产生大量无关格式差异。

用可视化编辑器搭建第一版

官方界面提供基础形状、流程形状和技术形状三类选择。可按以下顺序建立流程：

1. 添加开始、处理、判断和结束节点。
2. 双击标签填写简短动作或问题。
3. 拖拽建立连接，并为判断出口添加标签。
4. 使用对齐或自动排列整理结构。
5. 检查自动生成的 Mermaid 代码。

形状要表达含义：菱形用于判断，圆或终止形状用于事件，圆柱常用于数据库。不要只为装饰随意混用。

形状和样式为何适合视觉操作

节点工具可以调整形状、边框样式、边框颜色、背景色和文字色。样式变化会自动生成相应的 classDef 代码，因此无需手工记忆全部样式语法。

flowchart LR
    A[接收请求] --> B{校验通过？}
    B -- 是 --> C[执行任务]
    B -- 否 --> D[返回错误]

    classDef decision fill:#fff3bf,stroke:#d18b00,color:#222;
    classDef error fill:#ffe3e3,stroke:#c92a2a,color:#222;
    class B decision;
    class D error;

视觉设置完成后仍应查看生成代码，避免为每个节点产生大量难以维护的重复样式。

如何选择自动布局

当前 Visual Editor 提供层次布局和自适应布局。层次布局适合组织结构与决策树，自适应布局更适合连接关系复杂的流程。

自动排列只是布局建议，不会判断业务主次。应用后应确认：

• 主路径是否仍按自然阅读方向展开。
• 异常分支是否压过主流程。
• 边标签是否与其他连线重叠。
• 子图边界是否仍能表达责任范围。

复杂关系为何适合文本编辑

以下关系用代码更容易准确表达：

flowchart TD
    subgraph Client[客户端]
        A[提交请求]
        B[显示结果]
    end

    subgraph Server[服务端]
        C{鉴权成功？}
        D[执行业务]
        E[记录审计日志]
    end

    A --> C
    C -- 否 --> B
    C -- 是 --> D
    D --> E
    E --> B

通过文本可以快速看出所有跨子图连线。若只在画布中拖动，容易漏掉一条绕过鉴权或审计的路径。

批量修改时为何不应逐个点击

需要把十个节点的前缀统一修改，或把所有错误路径替换为同一标签时，逐个双击效率低且容易漏项。文本编辑器可以搜索目标并逐项确认。

批量替换也应谨慎：节点显示文字可能相同，但 ID 和业务含义不同。替换后通过预览检查节点数量和连线关系。

一个推荐的混合编辑流程

1. 在 Visual Editor 中创建节点、确定大致方向和分组。
2. 查看生成源码，统一节点 ID 和标签规范。
3. 在文本编辑器中补充复杂分支、循环和跨子图关系。
4. 回到画布，通过节点和边的双向高亮逐条走查。
5. 用视觉工具调整形状、颜色和布局。
6. 再次检查代码，确认没有意外的结构变化。
7. 保存版本并导出目标格式。

这套流程同时利用视觉反馈和文本精度，也让图表更容易纳入评审。

何时不应来回切换

下面几类任务应尽量固定使用文本编辑器：

• 必须保留现有源码格式和注释。
• 正在处理一个很小的补丁。
• 自动格式化会造成大量无关差异。
• 图表类型尚未被 Visual Editor 完整支持。

反过来，在会议现场共同梳理流程时，频繁切换到代码可能打断讨论，此时可先在画布完成结构，会议后再整理源码。

哪些图表类型支持可视化编辑

当前官方文档列出的支持类型包括流程图、类图、时序图、状态图、思维导图、实体关系图和需求图。支持范围可能继续变化，开始前应以当前界面为准。

“支持”也不代表每种图表的所有语法都能通过画布修改。遇到复杂特性时，可以保留源码并使用文本编辑器。

图标、图片和子图怎么选

Visual Editor 可以搜索图标、设置图标外观，也可以通过图片地址添加图像，并可在画布中新增子图、把节点拖入分组。

添加外部图片前要确认来源、访问稳定性和授权。内部架构图不应引用需要登录或会过期的图片地址。子图则应代表真实边界，例如团队、服务、阶段或信任区域，而不是只为让画面更满。

主题和 Look 有什么区别

主题主要控制颜色和字体，Look 控制整体渲染风格。官方当前提供多种主题，以及 Neo、手绘和经典等视觉风格。

选择时以用途为准：正式技术文档强调清晰和稳定，早期草图可以使用手绘风格，暗色主题则需要检查投影、打印和嵌入页面后的对比度。

多人协作适合哪种编辑器

业务人员通常更容易在 Visual Editor 中评论节点和关系，开发人员则更适合通过源码核对接口与状态。评论可以在两种编辑视图中使用，多人实时修改时仍应划分范围。

• 会议中用画布共同确认结构。
• 会后由维护者整理节点 ID 和源码。
• 复杂逻辑变更通过文本差异评审。
• 最终版本回画布进行可读性验收。

如何判断一次修改是否安全

1. 修改前保存源码或创建版本。
2. 明确本次改变的是结构、逻辑还是样式。
3. 选择最适合该任务的编辑器。
4. 修改后比较节点数、边数和关键路径。
5. 保存并重新打开，确认结果可复现。
6. 导出后检查裁切、字体和颜色。

常见问题

不懂 Mermaid 语法是否只能用可视化编辑器？

可以从可视化编辑器开始，但建议逐步理解节点 ID、箭头和子图。即使不手写全部代码，也能用源码检查自动生成结果。

可视化编辑后为什么代码差异很大？

Visual Editor 会自动美化和重构格式。如果必须保持精确排版，应回退并仅使用文本编辑器完成修改。

文本修改后画布布局变了怎么办？

Mermaid 会根据结构重新计算布局。先确认业务关系无误，再使用排列工具整理；对位置要求极高的图应保存、重载和导出验证。

图表很复杂时是否更应该使用画布？

画布适合观察整体，但精确连接、子图和批量修改通常更适合文本。复杂任务最好在两者之间按操作类型切换。

总结

Mermaid Visual Editor 适合快速构思、拖拽连接、选择形状和调整样式，文本编辑器适合精确语法、复杂逻辑、子图和版本评审。两者保持同步，最佳实践是按任务选择而非按个人身份选择。唯一需要特别警惕的是可视化编辑会自动格式化源码；当原始排版必须保持不变时，应只使用文本编辑器。