diff --git a/docs/mermaid-size-optimization.md b/docs/mermaid-size-optimization.md new file mode 100644 index 0000000..92eab28 --- /dev/null +++ b/docs/mermaid-size-optimization.md @@ -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） +- ✅ 创建尺寸优化测试文件 diff --git a/style.css b/style.css index f3e736b..b0ef617 100644 --- a/style.css +++ b/style.css @@ -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 错误提示样式 ---------- */ diff --git a/tests/test-mermaid-size-optimization.html b/tests/test-mermaid-size-optimization.html new file mode 100644 index 0000000..5438264 --- /dev/null +++ b/tests/test-mermaid-size-optimization.html @@ -0,0 +1,383 @@ + + + + + + Mermaid 图表尺寸优化测试 + + + + + + +

🎨 Mermaid 图表尺寸优化测试

+

本页面用于测试 Mermaid 图表的尺寸优化，确保低内容图表不会显示过大。

+ + +
+

测试 1: 极简图表（2-3个节点）

+ +
+

1.1 简单流程图（2个节点）

+

✅ 预期：图表高度不超过 600px，居中显示

+

优化前：可能显示超大，占据整个屏幕

+
+
+flowchart TD + A[开始] --> B[结束] +
+
+
+ +
+

1.2 简单流程图（3个节点）

+

✅ 预期：图表高度不超过 600px，居中显示

+
+
+flowchart LR + A[输入] --> B[处理] --> C[输出] +
+
+
+ +
+

1.3 简单判断流程

+

✅ 预期：图表高度不超过 600px，居中显示

+
+
+flowchart TD + A[用户] --> B{登录?} + B -->|是| C[首页] + B -->|否| D[登录页] +
+
+
+
+ + +
+

测试 2: 中等复杂度图表（5-10个节点）

+ +
+

2.1 标准流程图

+

✅ 预期：图表高度不超过 600px，自适应内容

+
+
+flowchart TD + A[开始] --> B[输入数据] + B --> C{数据有效?} + C -->|是| D[处理数据] + C -->|否| E[显示错误] + D --> F[保存结果] + E --> G[结束] + F --> G +
+
+
+ +
+

2.2 时序图

+

✅ 预期：图表高度不超过 600px

+
+
+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: 显示结果 +
+
+
+
+ + +
+

测试 3: 复杂图表（10+个节点）

+ +
+

3.1 复杂流程图

+

✅ 预期：图表高度限制在 600px，出现滚动条

+

优化：超过最大高度时，容器会出现垂直滚动条

+
+
+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[结束] +
+
+
+ +
+

3.2 类图

+

✅ 预期：图表高度限制在 600px

+
+
+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 +
+
+
+
+ + +
+

测试 4: 横向图表（宽度测试）

+ +
+

4.1 横向流程图

+

✅ 预期：宽度自适应，出现横向滚动条

+
+
+flowchart LR + A[步骤1] --> B[步骤2] --> C[步骤3] --> D[步骤4] --> E[步骤5] + E --> F[步骤6] --> G[步骤7] --> H[步骤8] --> I[步骤9] --> J[步骤10] +
+
+
+
+ + +
+

测试 5: 响应式适配

+ +
+

5.1 移动端适配

+

✅ 预期：在移动端（<768px）高度限制为 500px

+

请调整浏览器窗口大小测试

+
+
+flowchart TD + A[移动端] --> B[平板] + B --> C[桌面端] + A --> D[响应式] + B --> D + C --> D +
+
+
+
+ + +
+

📋 测试检查清单

+ +
+ + +
+

🎯 优化说明

+

主要改进：

+
    +
  1. 最大高度限制：SVG 最大高度设置为 600px（桌面端）
    2. +
  2. 居中显示：使用 flexbox 让图表在容器中居中
    3. +
  3. 宽度自适应：使用 width: auto !important 让图表保持原始宽高比
    4. +
  4. 响应式适配： +
      +
    • 平板（<768px）：最大高度 500px
      • +
    • 手机（<480px）：最大高度 400px
      • +
    +
    5. +
  5. 最小高度：容器最小高度 100px，避免空白过小
    6. +
+ +

CSS 关键属性：

+ 
.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;
+}
+
+ + + + +