在HTML文件中直接嵌入Mermaid图表：完整教程-html教程-PHP中文网

在HTML文件中直接嵌入Mermaid图表：完整教程

霞舞

发布： 2025-12-08 15:50:40

原创

398人浏览过

在HTML文件中直接嵌入Mermaid图表：完整教程

本教程将详细指导您如何在标准的html文件中直接集成mermaid图表。通过引入mermaid的es模块cdn并进行简单的javascript初始化，您可以轻松地在网页上渲染流程图、时序图等，摆脱对外部预览工具的依赖，实现图表的原生展示。

在日常开发和文档撰写中，我们经常需要绘制各种图表来辅助理解和沟通，例如流程图、时序图、甘特图等。Mermaid是一个基于文本的图表绘制工具，它允许开发者使用简单的Markdown风格语法来生成复杂的图表。虽然Mermaid常与Markdown编辑器或预览工具配合使用，但有时我们需要将其直接嵌入到HTML文件中，以便在Web页面中原生展示。本文将详细介绍如何在HTML文件中直接集成Mermaid图表。

核心步骤：引入Mermaid库并初始化

要在HTML文件中直接渲染Mermaid图表，主要涉及两个步骤：首先，通过CDN引入Mermaid的JavaScript库；其次，通过JavaScript代码初始化Mermaid，使其能够识别并渲染HTML中的图表定义。

1. 引入Mermaid库

Mermaid提供了ES模块（ESM）版本，可以直接通过script type="module"标签从CDN导入。这种方式简洁高效，无需额外的构建工具。

立即学习“前端免费学习笔记（深入）”；

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
    // ... 后续初始化代码
</script>

登录后复制

这里我们从cdn.jsdelivr.net引入了Mermaid的ESM版本。@9表示引入Mermaid的第9个主版本，您可以根据需要调整版本号。

2. 初始化Mermaid

导入Mermaid库后，需要对其进行初始化，告诉它何时以及如何渲染页面中的图表。最常见的初始化方式是设置startOnLoad: true，这会使Mermaid在页面加载完成后自动查找并渲染所有带有特定CSS类的图表定义。

一览妙笔

自媒体、编剧、营销人员写作工具

查看详情

mermaid.initialize({ startOnLoad: true });

登录后复制

将上述初始化代码放置在导入Mermaid的script标签内，即可完成自动渲染的配置。

完整示例：在HTML中嵌入Mermaid图表

下面是一个完整的HTML文件示例，演示了如何嵌入不同类型的Mermaid图表：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>在HTML中嵌入Mermaid图表示例</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            margin: 20px;
            line-height: 1.6;
        }
        h1, h2 {
            color: #333;
        }
        .mermaid {
            margin: 20px 0;
            border: 1px solid #eee;
            padding: 15px;
            border-radius: 5px;
            background-color: #f9f9f9;
            overflow-x: auto; /* 防止图表过宽时溢出 */
        }
    </style>
</head>
<body>

    <h1>Mermaid图表在HTML文件中的直接集成</h1>

    <p>以下是一个简单的流程图示例，展示了决策和分支逻辑：</p>
    <div class="mermaid">
        graph TD
            A[开始] --> B{处理数据};
            B -- 是 --> C[生成报告];
            B -- 否 --> D[等待输入];
            C --> E[结束];
            D --> A;
    </div>

    <p>这是一个C4组件图示例，用于描述系统架构中的组件关系：</p>
    <div class="mermaid">
        C4Component
            title 用户认证流程的组件图
            Component(Frontend, "Web Frontend", "用户界面")
            Component(AuthService, "认证服务", "处理用户登录/注册")
            Component(Database, "用户数据库", "存储用户信息")

            Rel(Frontend, AuthService, "调用认证API")
            Rel(AuthService, Database, "读写用户数据")
    </div>

    <!-- 引入Mermaid库并初始化 -->
    <script type="module">
        import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9/dist/mermaid.esm.min.mjs';
        // 初始化Mermaid，设置startOnLoad为true，使其在页面加载时自动渲染所有class="mermaid"的元素
        mermaid.initialize({ startOnLoad: true });
    </script>

</body>
</html>

登录后复制

代码解析：

...
: 这是Mermaid图表内容的容器。Mermaid库在初始化时会查找所有带有mermaid类的div元素，并将其内部的文本内容解析为图表。
Mermaid图表语法: graph TD ... 和 C4Component ... 是Mermaid的图表定义语法。您可以在Mermaid官方文档中找到更多图表类型的语法。
: 使用type="module"是为了能够使用import语句导入ES模块。这种方式是现代JavaScript模块加载的标准实践。
import mermaid from '...': 从CDN导入Mermaid库。请注意，这里的URL指向的是ESM（ECMAScript Module）版本。
mermaid.initialize({ startOnLoad: true });: 这是Mermaid的初始化函数。
- startOnLoad: true：告诉Mermaid在文档加载完成后自动扫描DOM，并渲染所有class="mermaid"的元素。

注意事项与最佳实践

Mermaid版本选择: CDN链接中的版本号（例如@9）决定了您使用的Mermaid版本。建议使用稳定版本，并定期检查是否有重要的更新或安全补丁。
图表容器: 务必将Mermaid图表定义放在一个带有class="mermaid"的HTML元素（通常是div）中。Mermaid默认会查找这些元素进行渲染。
初始化选项: mermaid.initialize()函数接受一个配置对象，您可以利用它来自定义Mermaid的行为，例如：
- theme: 设置图表主题，如'default', 'forest', 'dark', 'neutral'.
- logLevel: 控制日志输出级别。
- securityLevel: 调整渲染时的安全级别，默认为'strict'.
- 更多选项请参考Mermaid官方文档。
异步加载: type="module"的脚本是默认异步加载和执行的，不会阻塞HTML解析。这对于页面性能是有益的。
错误处理: 如果您的Mermaid图表语法有误，Mermaid通常会在控制台输出错误信息，并且图表可能无法正确渲染。请检查控制台以获取调试信息。
CDN稳定性: 虽然CDN通常非常稳定，但在生产环境中，您可能需要考虑将Mermaid库下载到本地服务器，以避免对外部网络的依赖。