解决 sigma.js 容器尺寸变化后图形渲染异常或空白的问题

一、问题具体表现与底层脱节机理

在日常开发中，当开发者给 sigma.js 绑定的 <div id="container"> 容器改变大小（例如用户拖动分栏、折叠侧边导航，或浏览器窗口尺寸变化）时，界面往往出现两类典型故障：

• 图形几何畸变与拾取偏移：原先正圆形的节点被横向压扁或纵向拉伸变成椭圆；当鼠标悬停在可见节点上方时无法触发高亮，反而鼠标挪到空白位置时却意外弹出了标签或提示框。
• 全画布空白或上下文丢失：将放置图谱的 Tab 标签页切换到后台，再切换回前台时，容器内空空如也；或者在弹窗打开动画期间初始化图谱，图谱只以极其微小的尺寸缩在左上角。

出现这些异常的原因，在于 sigma.js 的现代架构依赖于多层 Canvas（包含底层负责节点与连线渲染的 WebGL Canvas、负责标签与辅助图层的 2D Canvas，以及顶层的交互捕获层）。在浏览器渲染机制中，DOM 容器的 CSS 宽高仅决定了元素在屏幕上的排版流，而 Canvas 内部绘图缓冲区的物理像素是由元素的 width 与 height 属性决定的。

当宿主容器的 CSS 宽度从 600px 变大到 900px 时，如果未主动触发 sigma.js 的重新度量：

1. 内部 Canvas 元素的绘制缓冲区依然保持在初始的 600px。
2. 浏览器渲染引擎为了填满 900px 的 CSS 盒模型，会将原有的 600px 位图进行双线性插值强行拉伸，导致整张图谱像素模糊并发生比例失调。
3. WebGL 上下文中的 gl.viewport 与相机投影矩阵依然锚定在旧的纵横比（Aspect Ratio）上，由屏幕像素坐标反算到图谱世界坐标的矩阵未能更新，导致射线检测（Raycasting）出现严重偏差。
4. 若容器隐藏（display: none），其 clientWidth 与 clientHeight 瞬间归零，此时如果试图刷新，会直接向 WebGL 分配 0 尺寸的帧缓冲区，引发严重渲染错误并残留永久空白。

二、标准修复方案：ResizeObserver 与防抖重绘

解决此问题的正确姿势不是粗暴地销毁并重新创建 sigma 实例，而是借助现代浏览器的 ResizeObserver API 实时监听宿主 DOM 容器的内容盒尺寸变动，在尺寸稳定后调用实例的 refresh() 方法，让 sigma.js 自动重新计算 Canvas 的像素分辨率、更新 WebGL 视口与投影相机。

在实现过程中，有两项必须严格遵守的工程细节：

• 零尺寸防护守卫：必须先判断容器的宽高是否均大于 0。若容器当前处于隐藏状态，尺寸为 0，必须直接阻断重绘逻辑，防止 WebGL 发生零除错误。
• requestAnimationFrame 防抖节流：容器尺寸变动（尤其是伴随 CSS 过渡动画或用户拖拽）会在数毫秒内连续发出数十次尺寸通知。连续调用 refresh() 会强迫 GPU 频繁重设缓冲区，造成明显的掉帧卡顿。利用 requestAnimationFrame 可以将同一渲染帧内的多次变动汇聚为单次重绘。

完整生产级代码实现

// 假设已有初始化好的 sigma 实例与容器节点
const container = document.getElementById("sigma-container");
const renderer = new Sigma(graph, container, { /* 渲染配置 */ });

let rafId = null;

// 创建响应式尺寸观察器
const resizeObserver = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const { width, height } = entry.contentRect;

    // 1. 零尺寸安全防御：容器被 display:none 或处于折叠 0 高度时跳过
    if (width <= 0 || height <= 0) {
      return;
    }

    // 2. 取消上一帧未执行的刷新任务，合并连续形变
    if (rafId !== null) {
      cancelAnimationFrame(rafId);
    }

    // 3. 延迟到浏览器下一帧统一执行重绘
    rafId = requestAnimationFrame(() => {
      // 触发 sigma 重新测量容器尺寸、同步像素比与重设 WebGL Viewport
      renderer.refresh();
      rafId = null;
    });
  }
});

// 启动针对图谱容器的监听
resizeObserver.observe(container);

// 组件卸载或页面销毁时的资源清理
function destroyGraph() {
  if (rafId !== null) {
    cancelAnimationFrame(rafId);
  }
  resizeObserver.disconnect();
  renderer.kill();
}

三、方案对比：全局 Window 监听与局部容器观察的关键差异

许多初次接触该问题的开发者常习惯直接使用 window.addEventListener("resize", ...) 来触发刷新。在看似简单的单页测试中这种做法偶能奏效，但在实际生产业务系统中，两种做法存在本质层面的机制差异。

我们设定一个在现代中后台界面中极为常见的场景：用户点击左侧导航栏的“收起/展开”按钮，导航栏宽度由 240px 缩为 64px，右侧内容区的图谱容器随 Flex 布局自适应向外撑开。在这一一致前提下对比两者的表现：

这一差异之所以关键，是因为现代 Web 前端早已全面迈入组件化时代，绝大多数容器的尺寸变化都源自组件局部的状态切换（如 Drawer 抽屉展开、Panel 面板拖拽调节、Grid 栅格列数重构），而非整个显示器视窗的变动。因此，以组件 DOM 容器本身作为监听基准是保证图谱自适应的不可或缺的基础。

四、高频边缘场景的治理策略

在实际生产部署中，除了常规的尺寸拉伸外，还有两种极具隐蔽性、容易导致界面崩溃或极度掉帧的边缘场景。

1. Tab 切换引发的零尺寸（Zero-Dimension）陷阱

当图谱位于非首屏 Tab 页时，许多 UI 框架（如 Ant Design、Element Plus 或 Bootstrap）默认使用 display: none 来隐藏未激活的内容。此时宿主容器脱离渲染树，其 clientWidth 与 clientHeight 会瞬间归零。

2. CSS 过渡动画（transition）期间的防抖保障

很多侧边栏折叠通常带有 transition: width 0.3s ease 的过渡动画。在 300ms 的动画周期内，宿主容器的宽度每一帧都在发生微小改变，ResizeObserver 会在极短时间内产生数十次回调。

如果每产生一次回调就执行一次 refresh()，GPU 需要持续重新分配纹理与更新多层 Canvas 缓冲区，导致原本平滑的收折动画严重掉帧卡顿。通过 requestAnimationFrame 进行防抖不仅可以确保动画执行期间单帧只计算一次，还可以在容器节点上监听 transitionend 事件作为最终确认，在动画彻底停止时做一次终态刷新，兼顾流畅度与精度。

五、效果验证与健康自检清单

完成上述代码改造后，可通过以下 4 个明确步骤验证问题是否已彻底修复：

1. 物理分辨率对齐检查：打开浏览器开发者工具，选中 sigma 容器内部的 <canvas> 标签，检查其 HTML width 属性是否与容器的 clientWidth * window.devicePixelRatio 精确吻合。若两者完全匹配且没有 CSS 变形拉伸，说明像素分辨率已同步。
2. 极端边缘节点拾取测试：将鼠标移动到图谱最四周外沿的节点上。在进行侧边栏收折或窗口缩放后，观察节点悬停高亮、文字标签展示及点击事件是否依然与鼠标指针完全重合，不存在任何像素漂移。
3. 快速 Tab 来回切换压力测试：在多个 Tab 标签页之间高频来回点击切换，确认重新回到图谱页面时，画面能够即刻恢复完整渲染，无白屏、无黑块，控制台无 WebGL 报错。
4. 组件卸载与内存回收测试：在单页应用（SPA）中切换路由进入与离开图谱页面，验证 ResizeObserver.disconnect() 与 renderer.kill() 是否正常执行，避免残留的观察器在后台持续调用已销毁的实例引起内存泄漏。

通过建立规范的 ResizeObserver 监听、设置严谨的零尺寸防护门限，并辅以 requestAnimationFrame 防抖调度，即可彻底消解 sigma.js 在各种复杂前端动态布局中因容器尺寸变动所产生的图形畸变与渲染空白问题。