---
title: "Mermaid 图表"
description: "开启 `movkNuxtDocs.mermaid` 并安装 mermaid 与 dompurify 后，语言为 `mermaid` 的代码块渲染为流程图、时序图、类图等图表，随亮暗主题切换，进入视口时才加载，并提供复制与全屏查看。"
canonical_url: "https://docs.mhaibaraai.cn/docs/writing/mermaid"
---
# Mermaid 图表

> 开启 `movkNuxtDocs.mermaid` 并安装 mermaid 与 dompurify 后，语言为 `mermaid` 的代码块渲染为流程图、时序图、类图等图表，随亮暗主题切换，进入视口时才加载，并提供复制与全屏查看。

## 启用

Mermaid 默认关闭。

### 安装依赖

```bash [pnpm]
pnpm add mermaid dompurify
```

```bash [npm]
npm install mermaid dompurify
```

```bash [yarn]
yarn add mermaid dompurify
```

```bash [bun]
bun add mermaid dompurify
```

### 开启功能开关

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],

  movkNuxtDocs: {
    mermaid: true
  }
})
```

> [!WARNING]
> See: /docs/guide/features
> 
> 开启 
> 
> mermaid
> 
>  但未安装依赖时，构建会直接失败，并在错误信息中给出需要安装的包。未开启时，
> 
> mermaid
> 
>  代码块按普通代码展示。

## 用法

用语言为 `mermaid` 的代码块编写图表：

````md
```mermaid
flowchart LR
    A[编写 Markdown] --> B{包含 MDC 组件?}
    B -->|是| C[渲染 Vue 组件]
    B -->|否| D[渲染 Prose 元素]
    C --> E[输出页面]
    D --> E
```
````

- 跟随站点亮暗模式切换 Mermaid 主题
- 进入视口后才加载 `mermaid` 并渲染，不影响首屏
- 渲染结果经 DOMPurify 清理，Mermaid 以 `securityLevel: 'strict'` 运行
- 悬停时右上角显示复制源码与全屏查看按钮

### 文件名

与普通代码块一样，在方括号中写文件名，显示在图表顶部：

````md
```mermaid [ai-chat.mmd]
sequenceDiagram
    ...
```
````

## 图表类型

### 类图

`classDiagram` 描述类型与继承关系：

```mermaid
classDiagram
    class Page {
        +String title
        +String description
        +String path
    }
    class DocsPage {
        +String category
        +Link[] links
    }
    class ReleasePage {
        +String tag
        +Date publishedAt
    }
    Page <|-- DocsPage
    Page <|-- ReleasePage
```

### 状态图

`stateDiagram-v2` 描述状态流转：

```mermaid
stateDiagram-v2
    [*] --> 草稿
    草稿 --> 审阅中: 提交 PR
    审阅中 --> 草稿: 需要修改
    审阅中 --> 已发布: 合并
    已发布 --> [*]
```

### 饼图

`pie` 展示占比：

```mermaid
pie title 示例：页面类型占比
    "指南" : 11
    "AI" : 5
    "写作" : 6
    "组件" : 7
    "参考" : 14
```

### 甘特图

`gantt` 展示计划与里程碑：

```mermaid
gantt
    title 示例：版本发布计划
    dateFormat YYYY-MM-DD
    section 开发
        功能实现    :a1, 2026-09-01, 21d
        文档重写    :a2, after a1, 14d
    section 发布
        Beta 测试   :b1, after a2, 7d
        正式发布    :milestone, after b1, 0d
```

### 实体关系图

`erDiagram` 描述数据实体及其关系：

```mermaid
erDiagram
    COLLECTION ||--o{ PAGE : contains
    COLLECTION {
        string name
        string locale
    }
    PAGE ||--o{ SECTION : has
    PAGE {
        string path PK
        string title
        string category
    }
    SECTION {
        string id PK
        string heading
    }
```

> [!TIP]
> See: https://mermaid.js.org/intro/
> 
> 更多图表类型与语法见 Mermaid 官方文档。

## 自定义样式

在 `app/app.config.ts` 的 `ui.prose.mermaid` 中覆盖各插槽的类名：

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    prose: {
      mermaid: {
        slots: {
          root: 'my-8 border-primary/40',
          diagram: 'bg-default p-6'
        }
      }
    }
  }
})
```

默认主题：

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    prose: {
      mermaid: {
        slots: {
          root: 'relative my-5 group border border-muted rounded-md overflow-hidden',
          header: 'flex items-center gap-1.5 border-b border-muted bg-default px-4 py-3',
          filename: 'text-default text-sm/6',
          icon: 'size-4 shrink-0',
          toolbar: 'absolute top-2 right-2 flex gap-1 z-10 opacity-0 group-hover:opacity-100 transition-opacity',
          diagram: 'p-4 flex justify-center bg-elevated overflow-x-auto',
          loading: 'p-4 flex items-center justify-center gap-2 text-sm text-muted',
          error: 'p-4 flex items-center justify-center gap-2 text-sm text-error bg-error/10'
        },
        variants: {
          fullscreen: {
            true: {
              root: 'fixed inset-0 z-50 m-0 rounded-none bg-default flex flex-col',
              diagram: 'flex-1 overflow-auto',
              toolbar: 'opacity-100'
            }
          }
        }
      }
    }
  }
})
```

## API

### Props

```ts
/**
 * Props for the ProseMermaid component
 */
interface ProseMermaidProps {
  /**
   * 图表代码
   */
  code: string;
  /**
   * 图标
   */
  icon?: any;
  /**
   * 文件名
   */
  filename?: string | undefined;
  ui?: Partial<{ root: string; header: string; filename: string; icon: string; toolbar: string; diagram: string; loading: string; error: string; }> | undefined;
}
```

## Changelog

See commit history for [layer/modules/components/prose/Mermaid.vue](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/modules/components/prose/Mermaid.vue).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/components/prose/Mermaid.vue)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
