feat: 优化 Mermaid 图表尺寸显示

- 添加 SVG 最大高度限制(桌面端 600px)
- 使用 Flexbox 实现图表在容器中居中显示
- 添加响应式适配(平板 500px,手机 400px)
- 设置容器最小高度 100px,避免空白过小
- 使用 width: auto !important 保持图表原始宽高比
- 创建尺寸优化测试文件和文档

解决问题:
- 低内容图表(2-3 节点)不再显示过大
- 图表尺寸更加合理,视觉协调
- 复杂图表高度限制,出现滚动条
- 移动端体验优化
This commit is contained in:
2026-01-24 22:58:28 +08:00
parent 28f0a1265e
commit d0ae1dbed7
3 changed files with 583 additions and 0 deletions

View File

@@ -0,0 +1,184 @@
# Mermaid 图表尺寸优化
## 问题描述
在之前的实现中Mermaid 图表容器没有对 SVG 的高度进行限制,导致:
1. **低内容图表显示过大**:只有 2-3 个节点的简单流程图可能被渲染得非常大,占据整个屏幕
2. **用户体验不佳**:需要大量滚动才能看到后续内容
3. **视觉不协调**:简单图表与复杂图表的尺寸差异过大
## 优化方案
### 1. 最大高度限制
为 SVG 元素设置最大高度,避免图表显示过大:
```css
.mermaid-container svg {
max-height: 600px; /* 桌面端 */
}
```
### 2. 居中显示
使用 Flexbox 让图表在容器中居中显示:
```css
.mermaid-container {
display: flex;
justify-content: center;
align-items: center;
min-height: 100px;
}
```
### 3. 宽度自适应
使用 `width: auto !important` 让图表保持原始宽高比:
```css
.mermaid-container svg {
max-width: 100%;
width: auto !important;
height: auto;
}
```
### 4. 响应式适配
针对不同屏幕尺寸设置不同的最大高度:
```css
/* 桌面端 */
.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出现滚动条
- ✅ 响应式适配,移动端体验更好
## 测试方法
使用测试文件验证优化效果:
```bash
# 在浏览器中打开测试文件
tests/test-mermaid-size-optimization.html
```
### 测试检查清单
- [ ] 极简图表2-3 节点)不会显示过大
- [ ] 图表在容器中居中显示
- [ ] 中等复杂度图表显示正常
- [ ] 复杂图表高度限制在 600px
- [ ] 横向图表宽度自适应
- [ ] 夜间模式下图表显示正常
- [ ] 移动端响应式适配正常
## 技术细节
### CSS 关键属性
```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
- ✅ 创建尺寸优化测试文件

View File

@@ -919,12 +919,17 @@ article .wp-block-separator {
max-width: 100%;
opacity: 0;
animation: mermaidFadeIn 0.3s ease-in-out forwards;
display: flex;
justify-content: center;
align-items: center;
}
.mermaid-container svg {
max-width: 100%;
max-height: 600px;
height: auto;
display: block;
width: auto !important;
}
/* Mermaid 淡入动画 */
@@ -16631,11 +16636,17 @@ html.darkmode .mermaid-error-container .error-code code {
overflow-x: auto;
max-width: 100%;
transition: opacity 0.3s ease-in;
display: flex;
justify-content: center;
align-items: center;
min-height: 100px;
}
.mermaid-container svg {
max-width: 100%;
max-height: 600px;
height: auto;
width: auto !important;
display: block;
margin: 0 auto;
}
@@ -16664,6 +16675,7 @@ html.darkmode .mermaid-container {
.mermaid-container svg {
max-width: 100%;
max-height: 500px;
}
}
@@ -16672,6 +16684,10 @@ html.darkmode .mermaid-container {
padding: 10px;
margin: 10px 0;
}
.mermaid-container svg {
max-height: 400px;
}
}
/* ---------- Mermaid 错误提示样式 ---------- */

View File

@@ -0,0 +1,383 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mermaid 图表尺寸优化测试</title>
<link rel="stylesheet" href="../style.css">
<style>
body {
font-family: Arial, sans-serif;
max-width: 1200px;
margin: 0 auto;
padding: 20px;
background: #f5f5f5;
}
.test-section {
background: white;
padding: 20px;
margin-bottom: 20px;
border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.test-section h2 {
color: #5e72e4;
border-bottom: 2px solid #5e72e4;
padding-bottom: 10px;
margin-top: 0;
}
.test-case {
margin: 20px 0;
padding: 15px;
background: #f8f9fa;
border-left: 4px solid #5e72e4;
}
.test-case h3 {
margin-top: 0;
color: #333;
font-size: 16px;
}
.expected {
color: #28a745;
font-weight: bold;
margin: 10px 0;
}
.info {
color: #666;
font-size: 14px;
margin: 5px 0;
}
.toggle-theme {
position: fixed;
top: 20px;
right: 20px;
padding: 10px 20px;
background: #5e72e4;
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
z-index: 1000;
}
.toggle-theme:hover {
background: #4c63d2;
}
</style>
</head>
<body>
<button class="toggle-theme" onclick="toggleTheme()">🌓 切换夜间模式</button>
<h1>🎨 Mermaid 图表尺寸优化测试</h1>
<p>本页面用于测试 Mermaid 图表的尺寸优化,确保低内容图表不会显示过大。</p>
<!-- 测试 1: 极简图表 -->
<div class="test-section">
<h2>测试 1: 极简图表2-3个节点</h2>
<div class="test-case">
<h3>1.1 简单流程图2个节点</h3>
<p class="expected">✅ 预期:图表高度不超过 600px居中显示</p>
<p class="info">优化前:可能显示超大,占据整个屏幕</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart TD
A[开始] --> B[结束]
</div>
</div>
</div>
<div class="test-case">
<h3>1.2 简单流程图3个节点</h3>
<p class="expected">✅ 预期:图表高度不超过 600px居中显示</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart LR
A[输入] --> B[处理] --> C[输出]
</div>
</div>
</div>
<div class="test-case">
<h3>1.3 简单判断流程</h3>
<p class="expected">✅ 预期:图表高度不超过 600px居中显示</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart TD
A[用户] --> B{登录?}
B -->|是| C[首页]
B -->|否| D[登录页]
</div>
</div>
</div>
</div>
<!-- 测试 2: 中等复杂度图表 -->
<div class="test-section">
<h2>测试 2: 中等复杂度图表5-10个节点</h2>
<div class="test-case">
<h3>2.1 标准流程图</h3>
<p class="expected">✅ 预期:图表高度不超过 600px自适应内容</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart TD
A[开始] --> B[输入数据]
B --> C{数据有效?}
C -->|是| D[处理数据]
C -->|否| E[显示错误]
D --> F[保存结果]
E --> G[结束]
F --> G
</div>
</div>
</div>
<div class="test-case">
<h3>2.2 时序图</h3>
<p class="expected">✅ 预期:图表高度不超过 600px</p>
<div class="mermaid-container">
<div class="mermaid">
sequenceDiagram
participant U as 用户
participant F as 前端
participant B as 后端
participant D as 数据库
U->>F: 提交表单
F->>B: 发送请求
B->>D: 查询数据
D-->>B: 返回结果
B-->>F: 返回响应
F-->>U: 显示结果
</div>
</div>
</div>
</div>
<!-- 测试 3: 复杂图表 -->
<div class="test-section">
<h2>测试 3: 复杂图表10+个节点)</h2>
<div class="test-case">
<h3>3.1 复杂流程图</h3>
<p class="expected">✅ 预期:图表高度限制在 600px出现滚动条</p>
<p class="info">优化:超过最大高度时,容器会出现垂直滚动条</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart TD
A[开始] --> B[初始化]
B --> C{检查权限}
C -->|有权限| D[加载配置]
C -->|无权限| E[显示错误]
D --> F{配置有效?}
F -->|是| G[连接数据库]
F -->|否| H[使用默认配置]
G --> I{连接成功?}
I -->|是| J[加载数据]
I -->|否| K[重试连接]
K --> L{重试次数<3?}
L -->|是| G
L -->|否| M[连接失败]
H --> J
J --> N[处理数据]
N --> O{处理成功?}
O -->|是| P[显示结果]
O -->|否| Q[显示错误]
P --> R[记录日志]
Q --> R
E --> R
M --> R
R --> S[结束]
</div>
</div>
</div>
<div class="test-case">
<h3>3.2 类图</h3>
<p class="expected">✅ 预期:图表高度限制在 600px</p>
<div class="mermaid-container">
<div class="mermaid">
classDiagram
class Animal {
+String name
+int age
+makeSound()
+eat()
}
class Dog {
+String breed
+bark()
+fetch()
}
class Cat {
+String color
+meow()
+scratch()
}
class Bird {
+boolean canFly
+sing()
+fly()
}
Animal <|-- Dog
Animal <|-- Cat
Animal <|-- Bird
</div>
</div>
</div>
</div>
<!-- 测试 4: 横向图表 -->
<div class="test-section">
<h2>测试 4: 横向图表(宽度测试)</h2>
<div class="test-case">
<h3>4.1 横向流程图</h3>
<p class="expected">✅ 预期:宽度自适应,出现横向滚动条</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart LR
A[步骤1] --> B[步骤2] --> C[步骤3] --> D[步骤4] --> E[步骤5]
E --> F[步骤6] --> G[步骤7] --> H[步骤8] --> I[步骤9] --> J[步骤10]
</div>
</div>
</div>
</div>
<!-- 测试 5: 响应式测试 -->
<div class="test-section">
<h2>测试 5: 响应式适配</h2>
<div class="test-case">
<h3>5.1 移动端适配</h3>
<p class="expected">✅ 预期:在移动端(<768px高度限制为 500px</p>
<p class="info">请调整浏览器窗口大小测试</p>
<div class="mermaid-container">
<div class="mermaid">
flowchart TD
A[移动端] --> B[平板]
B --> C[桌面端]
A --> D[响应式]
B --> D
C --> D
</div>
</div>
</div>
</div>
<!-- 测试结果检查清单 -->
<div class="test-section">
<h2>📋 测试检查清单</h2>
<ul style="list-style: none; padding: 0;">
<li style="margin: 10px 0;">
<input type="checkbox" id="check1">
<label for="check1">✅ 极简图表2-3节点不会显示过大高度合理</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check2">
<label for="check2">✅ 图表在容器中居中显示</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check3">
<label for="check3">✅ 中等复杂度图表显示正常,高度不超过 600px</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check4">
<label for="check4">✅ 复杂图表高度限制在 600px出现滚动条</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check5">
<label for="check5">✅ 横向图表宽度自适应,出现横向滚动条</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check6">
<label for="check6">✅ 夜间模式下图表显示正常</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check7">
<label for="check7">✅ 移动端(<768px高度限制为 500px</label>
</li>
<li style="margin: 10px 0;">
<input type="checkbox" id="check8">
<label for="check8">✅ 小屏幕(<480px高度限制为 400px</label>
</li>
</ul>
</div>
<!-- 优化说明 -->
<div class="test-section">
<h2>🎯 优化说明</h2>
<h3>主要改进:</h3>
<ol>
<li><strong>最大高度限制</strong>SVG 最大高度设置为 600px桌面端</li>
<li><strong>居中显示</strong>:使用 flexbox 让图表在容器中居中</li>
<li><strong>宽度自适应</strong>:使用 <code>width: auto !important</code> 让图表保持原始宽高比</li>
<li><strong>响应式适配</strong>
<ul>
<li>平板(<768px最大高度 500px</li>
<li>手机(<480px最大高度 400px</li>
</ul>
</li>
<li><strong>最小高度</strong>:容器最小高度 100px避免空白过小</li>
</ol>
<h3>CSS 关键属性:</h3>
<pre style="background: #f8f9fa; padding: 15px; border-radius: 4px; overflow-x: auto;"><code>.mermaid-container {
display: flex;
justify-content: center;
align-items: center;
min-height: 100px;
}
.mermaid-container svg {
max-width: 100%;
max-height: 600px;
height: auto;
width: auto !important;
}</code></pre>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
// 初始化 Mermaid
mermaid.initialize({
startOnLoad: true,
theme: 'default',
securityLevel: 'loose',
flowchart: {
useMaxWidth: false,
htmlLabels: true
}
});
// 切换夜间模式
function toggleTheme() {
document.documentElement.classList.toggle('darkmode');
const isDark = document.documentElement.classList.contains('darkmode');
// 重新初始化 Mermaid 以应用新主题
mermaid.initialize({
startOnLoad: false,
theme: isDark ? 'dark' : 'default',
securityLevel: 'loose',
flowchart: {
useMaxWidth: false,
htmlLabels: true
}
});
console.log(`[Theme] 切换到 ${isDark ? '夜间' : '日间'} 模式`);
}
// 页面加载完成后的日志
window.addEventListener('load', function() {
console.log('[Mermaid Size Test] 测试页面已加载');
console.log('[Mermaid Size Test] 请检查:');
console.log('[Mermaid Size Test] 1. 极简图表是否显示合理大小');
console.log('[Mermaid Size Test] 2. 图表是否在容器中居中');
console.log('[Mermaid Size Test] 3. 复杂图表是否有高度限制');
console.log('[Mermaid Size Test] 4. 响应式适配是否正常');
});
</script>
</body>
</html>