expo-mermaid

在 React Native / Expo 中纯原生渲染 Mermaid 图表，无需 WebView。

通过自定义解析器将 Mermaid 标记语言解析为数据结构，再使用 react-native-svg 直接绘制矢量图形。

特点

• 🚫 无 WebView：纯 JS 解析 + react-native-svg 原生渲染
• 📐 25 种图表：与 Mermaid.js 官方支持基本对齐
• 🌗 主题支持：支持 light / dark / auto（跟随系统）
• 🔤 TypeScript：完整类型导出

安装

npm install expo-mermaid react-native-svg

如果使用裸 React Native（非 Expo Managed），还需链接原生模块：

cd ios && pod install

快速开始

import { MermaidChart } from 'expo-mermaid';

<MermaidChart
  chart={`
flowchart LR
  A[开始] --> B{判断}
  B -- 是 --> C[处理]
  B -- 否 --> D[结束]
  `}
  width={340}
  height={200}
  theme="auto"
/>

主题与暗色模式

MermaidChart 支持三种主题模式：

• light：强制亮色
• dark：强制暗色（深色底 + 高对比文本/线条）
• auto：默认值，跟随系统外观（Appearance / useColorScheme）

示例：

<MermaidChart chart={chartText} width={360} height={240} theme="light" />
<MermaidChart chart={chartText} width={360} height={240} theme="dark" />
<MermaidChart chart={chartText} width={360} height={240} theme="auto" />

说明：当 backgroundColor 为默认值 transparent 且主题为暗色时，组件会自动使用暗色背景，保证文字与图形可读性。

支持的图表类型

共支持 25 种图表，涵盖 Mermaid.js 全部主要类型。

注意：本库尽力与 Mermaid.js 官方 语法对齐，但部分语法变体（如 flowchart-elk、init 指令、handDrawn 等）不受支持。支持情况可能随版本更新变化，如有疑问请以实际渲染结果为准。

| # | 类型 | 关键字 | 说明 | |---|------|--------|------| | 1 | 流程图 | flowchart / graph | LR / TB / RL / BT 方向；矩形、菱形、圆柱、圆形、六边形节点 | | 2 | 时序图 | sequenceDiagram | 参与者、实线/虚线消息箭头、激活框 | | 3 | 饼图 | pie | 弧形切片、百分比标签、图例 | | 4 | 甘特图 | gantt | 分组任务条、after 依赖、日期轴 | | 5 | 类图 | classDiagram | 类、属性、方法、继承/组合关系 | | 6 | 状态图 | stateDiagram / stateDiagram-v2 | 状态节点、转换箭头、复合状态 | | 7 | ER 图 | erDiagram | 实体、属性、关系（一对多等） | | 8 | XY 图表 | xychart-beta | 折线图、柱状图，支持多系列 | | 9 | 用户旅程图 | journey | 任务、评分、参与者分组 | | 10 | 象限图 | quadrantChart | 四象限分布、点标签 | | 11 | 时间轴 | timeline | 事件时间线，分组展示 | | 12 | 思维导图 | mindmap | 树形展开，多层级彩色节点 | | 13 | Git 图 | gitGraph | 分支、提交、合并、标签 | | 14 | ZenUML | zenuml | UML 序列图（复用时序图渲染器） | | 15 | 桑基图 | sankey-beta | 流量带宽图，节点列布局 | | 16 | 需求图 | requirementDiagram | 需求、元素、关系连线 | | 17 | 雷达图 | radar | 多轴多系列，填充多边形 | | 18 | 看板图 | kanban | 多列任务卡片 | | 19 | 块图 | block-beta | 自动布局块连接图 | | 20 | 报文图 | packet-beta | 网络协议报文字段 | | 21 | 架构图 | architecture-beta | 服务节点、分组、连接线 | | 22 | 树图 | treemap | 嵌套矩形层级结构 | | 23 | 韦恩图 | venn | 集合交叉关系 | | 24 | 石川图 | ishikawa / fishbone | 鱼骨/因果分析图 | | 25 | 文件树 | treeview | 目录结构树，文件/文件夹图标 |

用法示例

时序图

<MermaidChart
  chart={`
sequenceDiagram
  participant 前端
  participant 后端
  前端->>后端: 请求数据
  后端-->>前端: 返回结果
  `}
  width={340}
  height={220}
/>

甘特图

<MermaidChart
  chart={`
gantt
  title 项目排期
  dateFormat YYYY-MM-DD
  section 开发
  设计 :a1, 2024-01-01, 7d
  开发 :after a1, 14d
  `}
  width={340}
  height={180}
/>

思维导图

<MermaidChart
  chart={`
mindmap
  root((核心))
    分支A
      子节点A1
    分支B
      子节点B1
  `}
  width={340}
  height={260}
/>

看板图

<MermaidChart
  chart={`
kanban
  Todo
    任务A
    任务B
  In Progress
    任务C
  Done
    任务D
  `}
  width={400}
  height={220}
/>

Props

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | chart | string | 必填 | Mermaid 标记字符串 | | width | number | 320 | 渲染宽度（px） | | height | number | 300 | 渲染高度（px） | | backgroundColor | string | 'transparent' | 背景色 | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | 图表主题；auto 跟随系统 |

Peer Dependencies

| 包 | 版本要求 | |----|---------| | react | >=18.0.0 | | react-native | >=0.70.0 | | react-native-svg | >=13.0.0 | | expo | >=50.0.0（可选，Expo Managed 项目） |

项目结构

src/
├── components/
│   └── MermaidChart.tsx      # 主组件：解析并分发到对应渲染器
├── parsers/
│   ├── types.ts              # 所有图表的共享数据类型
│   ├── flowchart.ts          # 流程图 / graph
│   ├── sequence.ts           # 时序图
│   ├── pie.ts                # 饼图
│   ├── gantt.ts              # 甘特图
│   ├── classDiagram.ts       # 类图
│   ├── stateDiagram.ts       # 状态图
│   ├── erDiagram.ts          # ER 图
│   ├── zenuml.ts             # ZenUML → 时序图
│   ├── gitGraph.ts           # Git 图
│   ├── sankey.ts             # 桑基图
│   ├── requirementDiagram.ts # 需求图
│   ├── radar.ts              # 雷达图
│   ├── kanban.ts             # 看板图
│   ├── blockDiagram.ts       # 块图
│   ├── packet.ts             # 报文图
│   ├── architecture.ts       # 架构图
│   ├── treemap.ts            # 树图
│   ├── ishikawa.ts           # 石川图
│   └── treeview.ts           # 文件树
├── renderers/
│   ├── FlowchartRenderer.tsx
│   ├── SequenceRenderer.tsx
│   ├── PieRenderer.tsx
│   ├── GanttRenderer.tsx
│   ├── ClassRenderer.tsx
│   ├── StateRenderer.tsx
│   ├── ErRenderer.tsx
│   ├── XyChartRenderer.tsx
│   ├── JourneyRenderer.tsx
│   ├── QuadrantRenderer.tsx
│   ├── TimelineRenderer.tsx
│   ├── MindmapRenderer.tsx
│   ├── GitGraphRenderer.tsx
│   ├── SankeyRenderer.tsx
│   ├── RequirementRenderer.tsx
│   ├── RadarRenderer.tsx
│   ├── KanbanRenderer.tsx
│   ├── BlockRenderer.tsx
│   ├── PacketRenderer.tsx
│   ├── ArchitectureRenderer.tsx
│   ├── TreemapRenderer.tsx
│   ├── VennRenderer.tsx
│   ├── IshikawaRenderer.tsx
│   └── TreeViewRenderer.tsx
└── index.ts                  # 统一导出

技术方案

Mermaid 标记字符串
       │
       ▼
  纯 JS 解析器（无 DOM 依赖）
  ├── 自定义手写解析器（大部分图表）
  └── @mermaid-js/parser（部分图表）
       │
       ▼
  中间数据结构（节点/边/任务…）
       │
   ┌───┴───┐
   │ dagre │  ← 有向图自动布局（纯 JS，用于流程图/ER/类图等）
   └───┬───┘
       │
       ▼
  react-native-svg 原生渲染

运行时依赖

| 包 | 用途 | |----|------| | react-native-svg | 原生 SVG 渲染引擎（peer dependency） | | dagre | 有向图自动布局算法（纯 JS） | | @mermaid-js/parser | 部分图表的官方 Langium 解析器 |

License

MIT