argon-theme/docs/mermaid-size-optimization.md

Mermaid 图表尺寸优化

问题描述

在之前的实现中，Mermaid 图表容器没有对 SVG 的高度进行限制，导致：

1. 低内容图表显示过大：只有 2-3 个节点的简单流程图可能被渲染得非常大，占据整个屏幕
2. 用户体验不佳：需要大量滚动才能看到后续内容
3. 视觉不协调：简单图表与复杂图表的尺寸差异过大

优化方案

1. 最大高度限制

为 SVG 元素设置最大高度，避免图表显示过大：

.mermaid-container svg {
	max-height: 600px;  /* 桌面端 */
}

2. 居中显示

使用 Flexbox 让图表在容器中居中显示：

.mermaid-container {
	display: flex;
	justify-content: center;
	align-items: center;
	min-height: 100px;
}

3. 宽度自适应

使用 width: auto !important 让图表保持原始宽高比：

.mermaid-container svg {
	max-width: 100%;
	width: auto !important;
	height: auto;
}

4. 响应式适配

针对不同屏幕尺寸设置不同的最大高度：

/* 桌面端 */
.mermaid-container svg {
	max-height: 600px;
}

/* 平板（<768px） */
@media screen and (max-width: 768px) {
	.mermaid-container svg {
		max-height: 500px;
	}
}

/* 手机（<480px） */
@media screen and (max-width: 480px) {
	.mermaid-container svg {
		max-height: 400px;
	}
}

优化效果

优化前

• ❌ 简单图表（2-3 节点）可能显示超大，占据整个屏幕
• ❌ 图表尺寸不可控，用户体验差
• ❌ 需要大量滚动才能看到后续内容

优化后

• ✅ 简单图表显示合理大小，不会过大
• ✅ 图表在容器中居中显示，视觉协调
• ✅ 复杂图表高度限制在 600px，出现滚动条
• ✅ 响应式适配，移动端体验更好

测试方法

使用测试文件验证优化效果：

# 在浏览器中打开测试文件
tests/test-mermaid-size-optimization.html

测试检查清单

• 极简图表（2-3 节点）不会显示过大
• 图表在容器中居中显示
• 中等复杂度图表显示正常
• 复杂图表高度限制在 600px
• 横向图表宽度自适应
• 夜间模式下图表显示正常
• 移动端响应式适配正常

技术细节

CSS 关键属性

.mermaid-container {
	/* 使用 Flexbox 居中 */
	display: flex;
	justify-content: center;
	align-items: center;
	
	/* 最小高度，避免空白过小 */
	min-height: 100px;
	
	/* 其他样式 */
	background: var(--card-background);
	border-radius: var(--card-radius);
	padding: 20px;
	margin: 20px 0;
	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
	overflow-x: auto;
	max-width: 100%;
	transition: opacity 0.3s ease-in;
}

.mermaid-container svg {
	/* 宽度限制 */
	max-width: 100%;
	width: auto !important;
	
	/* 高度限制 */
	max-height: 600px;
	height: auto;
	
	/* 居中显示 */
	display: block;
	margin: 0 auto;
}

为什么使用 width: auto !important

Mermaid 会自动设置 SVG 的 width 属性，可能导致图表过大。使用 !important 强制覆盖，让浏览器根据 max-width 和 max-height 自动计算宽度，保持原始宽高比。

为什么使用 Flexbox

使用 Flexbox 可以轻松实现图表在容器中的居中显示，无论图表大小如何变化，都能保持居中对齐。

兼容性

• ✅ 现代浏览器（Chrome, Firefox, Safari, Edge）
• ✅ 移动端浏览器
• ✅ 夜间模式
• ✅ 响应式布局

注意事项

1. 滚动条：当图表高度超过最大高度时，容器会出现垂直滚动条
2. 宽高比：图表会保持原始宽高比，不会变形
3. 性能：优化不会影响 Mermaid 的渲染性能
4. 兼容性：与现有的 Mermaid 功能完全兼容

相关文件

• style.css - Mermaid 容器样式定义
• tests/test-mermaid-size-optimization.html - 尺寸优化测试文件
• docs/mermaid-usage-guide.md - Mermaid 使用指南
• docs/mermaid-troubleshooting.md - Mermaid 故障排除

更新日志

2026-01-24

• ✅ 添加 SVG 最大高度限制（600px）
• ✅ 使用 Flexbox 实现图表居中
• ✅ 添加响应式适配（平板 500px，手机 400px）
• ✅ 添加最小高度限制（100px）
• ✅ 创建尺寸优化测试文件