Pele mount()深度指南：让Mermaid图表自适应容器宽度与字体加载的5个技巧-尧图手机网站定制

【免费下载链接】pele

Renders Mermaid diagrams faster than you'd run from a volcano! 🌋

项目地址：https://gitcode.com/gh_mirrors/pe/pele

Pele 是一个同步、无运行时依赖的 Mermaid 图表渲染库，它把 Mermaid 文本直接渲染成 SVG。它的mount()函数专为浏览器而生：把图表放进一个 DOM 元素后，自动监听容器宽度变化、从 CSS 读取字体、并在字体加载完成后重新绘制。本文带你掌握 5 个实用技巧，让图表在任何布局下都显示得体。

为什么选 mount() 而不是 render()？

render()只给你一次性的 SVG 字符串，适合静态场景；mount()则返回一个Mounted句柄，持续"看护"图表：

import { mount } from 'pele'; mount(document.querySelector('#diagram'), text);

它背后做了三件关键的事（实现见 mount.ts）：

宽度监听：用ResizeObserver观察容器，宽度变化就按需重绘；
字体感知：从元素的计算样式读取--pele-font等 CSS 变量，并用document.fonts.ready等待字体就绪；
优雅降级：解析或绘制失败时，错误直接显示在元素内，页面不会崩溃。

技巧1：选对容器元素，让图表自动跟随宽度

mount()的第一原则写在源码注释里：元素宽度最好不要依赖它里面的内容，比如用一个块级容器。内部逻辑在 window.ts 中用clientWidth减去左右 padding 算出"可用宽度"，再传给渲染器。

#diagram { display: block; width: 100%; }

几个值得知道的细节：

场景	mount() 的行为
容器比图表窄	重新布局到可用宽度（如把横向图转为竖向）
容器被隐藏（宽度为 0）	不重绘，等元素重新可见时再画
图表本就不受宽度影响	只画一次，不做无用功
窄屏（默认 <640px）	横向图表自动转为竖向绘制，见`autoDirection`选项

其中autoDirection与directionBreakpoint两个选项定义在 types.ts，让你在手机上也能获得可读的布局。这套宽度自适应逻辑的完整行为可用 tests/mount.test.ts 中的用例对照验证。

技巧2：用 CSS 变量指定字体，图表即改即生效

你不需要在 JS 里传字体名。mount()会读取元素计算样式中的两个变量：

#diagram { --pele-font: 'Inter', sans-serif; /* 正文字体 */ --pele-font-mono: Menlo, monospace; /* 等宽字体 */ }

读取逻辑在 mount.ts 的 fontsFor()：如果 SVG 自身设置了--pele-font（元素不继承子元素的变量），它会以 SVG 上读到的值为准。这意味着切换主题时只改 CSS 变量、再调用refresh()，图表就能按新字体重排，无需手动传参。

技巧3：让字体加载"静默完成"，避免错位重绘

网页字体（web font）加载前，文字测量用的是回退字体的宽度，加载后图表可能"挤"了或"散"了。mount()内置了解决方案：

首次绘制时检查document.fonts.status是否为loading；
若是，通过共享的fonts.readyPromise 等待（同一字体集只等一次，见 settled()）；
字体就绪后调用forgetTextWidths()清空宽度缓存，再用真实字体重新测量和绘制。

整个过程对使用者透明：你只管声明字体，加载完成后图表会自动修正。这一机制在 tests/mount.test.ts 中有专门测试覆盖——包括"字体加载了但宽度没变化就不重绘"的优化路径。

技巧4：开启 zoom，缩小后的图表支持放大查看

当图表被压缩到容器宽度时，zoom默认为'auto'：用户可以直接在图表上双指捏合、按住 Ctrl/⌘ 滚轮、双击、拖动或按键盘+-0放大和移动视野。右上角还会自动出现一组缩放按钮。

mount(el, text, { zoom: { always: true, maxScale: 4, controls: true }, });

zoom 选项	含义
`true`/`'auto'`（默认）	任何图表 / 仅被缩小的图表可放大
`false`	完全禁用
对象形式	可配`always`、`maxScale`（默认3倍）、`controls`按钮、`labels`本地化文案

交互实现（指针、滚轮、手势、键盘）集中在 zoom.ts，按钮位置还能通过--pele-zoom-top等 CSS 变量调整，方便避让页面上其他元素。

技巧5：管好 Mounted 句柄的生命周期

mount()返回的句柄提供三个方法（定义见 Mounted 接口）：

const handle = mount(el, text); handle.update(newText); // 换一段图表文本，同元素重绘 handle.refresh(); // 主题/字体/布局变化后，按需重绘 handle.destroy(); // 停止监听，显示内容保留

update()：解析失败时保留上一张图（调暗）并在其底部叠加错误提示，而不是整块空白；
refresh()：切换主题色后改的是 CSS 变量，SVG 颜色会自动跟随，但字体变化需要它触发重绘；
destroy()：SPA 中卸载组件时务必调用，它会断开ResizeObserver、移除缩放交互和字体回调，避免内存泄漏。

另外两个常用回调：onRender在每次出图后触发，onError捕获解析/绘制失败；若展示不受信任的文本，记得提供sanitize选项把 SVG 交给宿主方的净化器（选项说明见 MountOptions）。

常见误区速查

❌ 把mount()用在宽度随内容撑开的行内元素上——容器会越画越宽，观察器反复触发。用块级、固定宽度的容器。
❌ 手动再套一层window.addEventListener('resize')——ResizeObserver已经覆盖宽度变化，重复监听只是浪费。
❌ 期望字体没加载完图表也是最终尺寸——加载期间图表可能短暂以回退字体绘制，属正常现象，加载完成会自动修正。
✅ 隐藏面板（如 Tab 页签、折叠区）里的图表不用特殊处理：mount()检测到宽度为 0 时不重绘，面板显示后自动按真实宽度画出。

写在最后

mount()把"容器宽度监听 + 字体生命周期 + 缩放交互 + 错误兜底"打包成一个函数调用，这正是 Pele 作为浏览器端渲染器的核心卖点。建议结合 src/mount.ts 的注释和 tests/mount.test.ts 的用例阅读，五分钟就能摸清每个边界行为——剩下的，交给 Pele 比火山喷发还快的渲染速度 🌋。