# Mermaid 预览与缩放开发说明

> 本文档用于前端开发和图表渲染联调。
>
> 更新日期：2026-09-06。代码基线：`a5c44c4`。

## 当前实现

工作区和静态 Markdown 通过 `mermaidService.ts` 串行渲染，使用主题变量与 Mermaid strict 模式。工作区由 `mermaidPreview.ts` 发布当前版本预览；`DiagramInteractions.vue` 提供缩放和大图交互。

- 行内按钮在悬停或键盘焦点进入时显示；触屏保留操作入口。
- 行内中键点击 SVG 后进入滚轮缩放，移动鼠标或窗口失焦退出。
- 大图直接使用滚轮缩放，缩放范围为 20%～500%。
- 行内首次缩放以实际显示宽度为基准，避免受容器限制的图表跳回原始宽度。
- 大图打开时根据原始比例与可用窗口宽高确定 100% 基准，清除旧滚动位置并居中；100% 不一定等于 SVG 原始像素宽度。
- 滚轮增量按时间和 delta 限制，宽度变化使用 180ms 过渡；支持减少动态效果偏好。
- 过渡期间根据鼠标位置补偿内外滚动容器。受滚动边界限制时，不能保证鼠标锚点在任意位置绝对不动。

## 文字裁切的原因与修复

Mermaid 的 HTML 标签放在固定尺寸的 SVG `foreignObject` 中。Milkdown 的正文段落规则会给内部 p 增加上下各 4px 内边距，导致关系标注超出文字框。工作区现在对图表内部 p 清除段落内边距和外边距，并继承图表行高、字重。

大图复制 SVG 时保留 `foreignObject`，先清理嵌入 HTML，再清理整个 SVG，移除脚本及事件属性。不能为了保留标签而关闭安全清理。

类图未声明方法时，其方法区为空是正常结构。排查时应先对照源码，再检查 DOM 标签、尺寸和裁切范围。

## 验证方法

在 frontend 目录执行：

```powershell
pnpm exec vitest run src/components/common/DiagramInteractions.spec.ts src/features/editor/diagramIntegration.spec.ts src/features/editor/mermaidPreview.spec.ts
pnpm exec vue-tsc -b
```

使用 Vault 中“功能演示/03 Mermaid 图表集.md”手动检查：

1. 检查流程图、时序图、类图、状态图、ER 图和甘特图。
2. 类图的 1、many、contains 应完整显示；查看内部 p 的 padding 应为 0。
3. 甘特图大图初始应完整适配；放大后可通过滚动条查看超出部分。
4. 连续滚轮输入不应首次跳大；移动鼠标后行内滚轮模式退出。
5. 关闭并重开大图，不保留上次滚动位置。

浏览器实测中，关系标注文字高度约 16.5px，对应 16.5px 的 SVG 标签框；contains 约 24px，对应 24px 框。该结果不替代所有主题、字体、浏览器的视觉验收。

相关格式范围见 [Markdown 渲染检查](Markdown渲染检查.md)。