⚡

美丽美人鱼图表渲染工具Skill beautiful-mermaid

美丽美人鱼图表渲染工具是一个TypeScript库，专用于将Mermaid图表高效渲染为SVG或ASCII/Unicode文本，支持超快性能、完整主题系统和零DOM依赖，适用于AI辅助编程、终端工作流和数据可视化应用。关键词：Mermaid图表，图表渲染，SVG，ASCII，主题系统，TypeScript，数据可视化工具。

数据可视化 0 次安装 0 次浏览 更新于 3/20/2026

name: beautiful-mermaid description: 当用户想要将Mermaid图表渲染为美丽的SVG或ASCII/Unicode艺术时，应使用此技能。当用户提到“Mermaid图表”、“图表渲染”、“流程图”、“序列图”或想要使用自定义主题生成视觉图表时使用。支持SVG和终端友好的ASCII输出，具有15个内置主题和VS Code主题集成。

美丽美人鱼图表渲染

概述

美丽美人鱼是一个TypeScript库，将Mermaid图表渲染为SVG或ASCII/Unicode文本，具有超快性能、完整主题支持和零DOM依赖。完美适用于AI辅助编程和终端工作流。

安装

npm install beautiful-mermaid
# 或
bun add beautiful-mermaid
# 或
pnpm add beautiful-mermaid

支持的图表类型

  • 流程图: graph TD, graph LR
  • 状态图: stateDiagram-v2
  • 序列图: sequenceDiagram
  • 类图: classDiagram
  • ER图: erDiagram

核心APIs

SVG渲染（异步）

import { renderMermaid } from 'beautiful-mermaid'

// 基本使用，自动生成颜色
const svg = await renderMermaid(`
  graph TD
    A[开始] --> B{决策}
    B -->|是| C[动作]
    B -->|否| D[结束]
`)

// 自定义颜色
const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6'
})

// 完整主题控制
const svg = await renderMermaid(diagram, {
  bg: '#0f0f0f',
  fg: '#e0e0e0',
  accent: '#ff6b6b',
  line: '#888888',
  muted: '#666666',
  surface: '#1a1a1a',
  border: '#333333',
  font: 'Inter',
  transparent: false
})

ASCII/Unicode渲染（同步）

import { renderMermaidAscii } from 'beautiful-mermaid'

// Unicode输出（默认，更美观）
const text = renderMermaidAscii(`
  graph LR
    A --> B --> C
`)

// 纯ASCII输出（最大兼容性）
const ascii = renderMermaidAscii(diagram, { useAscii: true })

// 自定义间距
const spaced = renderMermaidAscii(diagram, {
  paddingX: 4,
  paddingY: 2,
  boxBorderPadding: 1
})

主题系统

两色基础（单色模式）

库自动从bg和fg使用color-mix()生成完整颜色调色板：

// 最小主题 - 其他所有自动生成
const svg = await renderMermaid(diagram, {
  bg: '#FFFFFF',
  fg: '#27272A'
})

这衍生出：

  • 不同透明度的文本颜色
  • 节点填充和描边颜色
  • 连接线和箭头颜色
  • 次要和边缘标签颜色

丰富模式

覆盖特定颜色以进行精细控制：

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',      // 背景
  fg: '#a9b1d6',      // 主要前景
  line: '#7aa2f7',    // 线条和连接器
  accent: '#bb9af7',  // 高亮和强调
  muted: '#565f89',   // 次要文本
  surface: '#24283b', // 节点背景
  border: '#3b4261'   // 边框
})

内置主题

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// 可用主题
const themeNames = [
  'zinc-light',
  'zinc-dark',
  'tokyo-night',
  'tokyo-night-storm',
  'tokyo-night-light',
  'catppuccin-latte',
  'catppuccin-frappe',
  'catppuccin-macchiato',
  'catppuccin-mocha',
  'nord',
  'dracula',
  'github-light',
  'github-dark',
  'solarized-light',
  'one-dark'
]

// 使用内置主题
const svg = await renderMermaid(diagram, THEMES['tokyo-night'])

// 自定义内置主题
const svg = await renderMermaid(diagram, {
  ...THEMES.nord,
  accent: '#ff6b6b'
})

VS Code主题集成（Shiki）

将任何VS Code主题转换为图表颜色：

import { getSingletonHighlighter } from 'shiki'
import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid'

// 加载Shiki主题
const highlighter = await getSingletonHighlighter({
  themes: ['vitesse-dark', 'min-light', 'catppuccin-mocha']
})

// 转换主题为图表颜色
const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))

// 使用匹配编辑器颜色的渲染
const svg = await renderMermaid(diagram, colors)

实时主题切换

所有颜色都暴露为CSS自定义属性，无需重新渲染即可实现即时主题切换：

// 初始渲染
const svg = await renderMermaid(diagram, THEMES['github-light'])

// 在浏览器中，更新CSS变量以切换主题
document.documentElement.style.setProperty('--diagram-bg', '#0d1117')
document.documentElement.style.setProperty('--diagram-fg', '#c9d1d9')
// ... 等等

常见使用模式

模式：带ASCII输出的CLI工具

#!/usr/bin/env node
import { renderMermaidAscii } from 'beautiful-mermaid'
import { readFileSync } from 'fs'

const diagram = readFileSync(process.argv[2], 'utf-8')
console.log(renderMermaidAscii(diagram))

模式：主题切换器

import { renderMermaid, THEMES } from 'beautiful-mermaid'

async function renderWithTheme(diagram: string, themeName: string) {
  const theme = THEMES[themeName] || THEMES['zinc-dark']
  return await renderMermaid(diagram, theme)
}

模式：匹配系统深色模式

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const theme = isDark ? THEMES['tokyo-night'] : THEMES['github-light']
const svg = await renderMermaid(diagram, theme)

模式：透明背景用于覆盖层

const svg = await renderMermaid(diagram, {
  ...THEMES.nord,
  transparent: true
})

模式：批量渲染

const diagrams = [/* ... */]

// 并行渲染（快速！）
const svgs = await Promise.all(
  diagrams.map(d => renderMermaid(d, THEMES['one-dark']))
)

// 100+个图表在500毫秒内

选项参考

SVG选项（renderMermaid）

选项 类型 默认值 描述
bg 字符串 #FFFFFF 背景颜色
fg 字符串 #27272A 前景/文本颜色
line 字符串 自动 线条和连接器颜色
accent 字符串 自动 高亮和强调颜色
muted 字符串 自动 次要文本颜色
surface 字符串 自动 节点背景颜色
border 字符串 自动 边框颜色
font 字符串 Inter 字体家族
transparent 布尔值 false 透明背景

ASCII选项（renderMermaidAscii）

选项 类型 默认值 描述
useAscii 布尔值 false 使用ASCII代替Unicode
paddingX 数字 2 节点之间的水平间距
paddingY 数字 1 节点之间的垂直间距
boxBorderPadding 数字 1 框的内部填充

示例图表

流程图

graph TD
    A[开始] --> B{是否有效？}
    B -->|是| C[处理]
    B -->|否| D[错误]
    C --> E[完成]
    D --> E

序列图

sequenceDiagram
    participant 用户
    participant API
    participant DB

    用户->>API: 请求
    API->>DB: 查询
    DB-->>API: 结果
    API-->>用户: 响应

状态图

stateDiagram-v2
    [*] --> 空闲
    空闲 --> 处理中: 开始
    处理中 --> 成功: 完成
    处理中 --> 错误: 失败
    成功 --> [*]
    错误 --> 空闲: 重试

类图

classDiagram
    class 动物 {
        +String 名称
        +int 年龄
        +makeSound()
    }
    class 狗 {
        +bark()
    }
    动物 <|-- 狗

ER图

erDiagram
    用户 ||--o{ 订单 : 下订单
    订单 ||--|{ 订单项 : 包含
    产品 ||--o{ 订单项 : "被订购"

性能特点

  • 渲染速度: 100+个图表在500毫秒内
  • 依赖: 零DOM依赖（在Node.js中工作）
  • 同步: ASCII渲染完全同步
  • 打包大小: 轻量级纯TypeScript实现

调试

常见问题

1. Mermaid语法错误: 库不验证语法。首先使用官方Mermaid在线编辑器验证图表语法。

2. 缺少字体: SVG默认使用Inter字体。如果需要，用font选项覆盖。

3. 颜色不显示: 确保传递十六进制颜色（例如，#1a1b26，而不是rgb(26, 27, 38)）。

4. ASCII输出太窄: 增加paddingX和boxBorderPadding。

测试图表

// 在Node.js REPL中快速测试
import { renderMermaidAscii } from 'beautiful-mermaid'
console.log(renderMermaidAscii('graph LR; A --> B'))

集成模式

与Express.js

app.post('/render', async (req, res) => {
  const { diagram, theme } = req.body
  const svg = await renderMermaid(diagram, THEMES[theme])
  res.type('image/svg+xml').send(svg)
})

与CLI（Fish Shell）

#!/usr/bin/env fish

# 将Mermaid文件渲染为ASCII
function mmd-ascii
    node -e "
        import('beautiful-mermaid').then(({ renderMermaidAscii }) => {
            const fs = require('fs')
            const diagram = fs.readFileSync('$argv[1]', 'utf-8')
            console.log(renderMermaidAscii(diagram))
        })
    "
end

# 用法: mmd-ascii diagram.mmd

与文件监视器

import { watch } from 'fs'
import { renderMermaid, THEMES } from 'beautiful-mermaid'

watch('diagram.mmd', async (event, filename) => {
  const diagram = readFileSync(filename, 'utf-8')
  const svg = await renderMermaid(diagram, THEMES['tokyo-night'])
  writeFileSync('output.svg', svg)
})

资源

快速参考

// 导入
import { renderMermaid, renderMermaidAscii, THEMES, fromShikiTheme } from 'beautiful-mermaid'

// SVG（异步）
await renderMermaid(diagram, { bg: '#000', fg: '#fff' })
await renderMermaid(diagram, THEMES['tokyo-night'])

// ASCII（同步）
renderMermaidAscii(diagram)
renderMermaidAscii(diagram, { useAscii: true })

// Shiki集成
const colors = fromShikiTheme(shikiTheme)
await renderMermaid(diagram, colors)