sigma.js 快速上手：在原生 JS 与 React 中绘制第一个网络图

一、核心认知：sigma.js 与 graphology 的解耦架构

很多刚接触 sigma.js 的开发者常有一个误区：认为只需把一组节点数组传递给某个视图配置项就能自动出图。然而在 sigma.js v2 之后的现代版本中，其设计哲学经历了一次重大重构——sigma.js 本身不再承担图数据结构的维护与算法存储，而是将图数据完全托管给专门的图论库 graphology。

这种解耦带来了极其明确的分工：

• Graphology（数据层）：专门负责在内存中高效存储顶点（Nodes）、边（Edges）及其属性集合（如坐标 x, y、尺寸 size、标签 label、颜色 color 等），并提供丰富的图遍历、最短路径以及力导向布局算法支持。
• sigma.js（视图与交互层）：监听 Graphology 实例中的拓扑与属性变动事件，通过高效的 WebGL 着色器程序执行批量绘制，并在上层维护相机控制（平移、无极缩放、视角旋转）及鼠标拾取（Hover、Click）事件。

正因为采用了这种架构，无论你在原生脚本环境、Vue、Angular 还是 React 中使用，第一步永远是构造 Graphology 图拓扑，第二步才是将该图对象交给 Sigma 实例去绑定渲染。

二、原生 JavaScript 实战：四步绘制第一个网络图

在原生环境中使用 sigma.js 时，我们可以通过 npm 构建工具（如 Vite、Webpack）安装，也可以通过现代 CDN（如 unpkg 或 jsDelivr）通过 ES Module 方式引入。下面我们将按照实际工程的标准四步法完成基础网络图的搭建。

第 1 步：准备包含明确像素尺寸的 HTML 容器

WebGL 画布对宿主容器的尺寸有着严格要求。如果容器未设置具体的高度，其默认高度会坍缩为 0px，此时 WebGL 无法计算正确的投影矩阵，画布表面将呈现为完全空白且没有任何报错提示。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>Sigma.js 原生示例</title>
  <style>
    html, body {
      margin: 0;
      padding: 0;
      width: 100%;
      height: 100%;
      background: #142537;
    }
    /* 必须显式声明容器宽高 */
    #sigma-container {
      width: 100%;
      height: 100vh;
      overflow: hidden;
    }
  </style>
</head>
<body>
  <div id="sigma-container"></div>
  <script type="module" src="./main.js"></script>
</body>
</html>

第 2 步：安装依赖并装配 Graphology 图拓扑

如果是在标准 npm 项目中，首先执行依赖安装：

npm install graphology sigma

在 main.js 中，我们实例化一个 Graph 对象，并向其中添加若干节点与连线。请务必注意：sigma.js 要求渲染的节点必须包含有效的数值型 x 与 y 属性，否则渲染引擎无法确定其在 2D 平面上的初始投影位置。

import Graph from "graphology";
import Sigma from "sigma";

// 1. 实例化图数据结构
const graph = new Graph();

// 2. 添加带视觉属性的节点
graph.addNode("node-a", {
  label: "核心调度网关",
  x: 0,
  y: 0,
  size: 18,
  color: "#77B9AE", // 强调色浅青
});

graph.addNode("node-b", {
  label: "应用集群 A",
  x: 10,
  y: 8,
  size: 14,
  color: "#83ADD0", // 主色柔蓝
});

graph.addNode("node-c", {
  label: "应用集群 B",
  x: -8,
  y: 12,
  size: 14,
  color: "#83ADD0",
});

graph.addNode("node-d", {
  label: "分布式存储",
  x: 2,
  y: 20,
  size: 12,
  color: "#EAF2F8",
});

// 3. 建立节点之间的连线
graph.addEdge("node-a", "node-b", { size: 2, color: "#2E4D6E" });
graph.addEdge("node-a", "node-c", { size: 2, color: "#2E4D6E" });
graph.addEdge("node-b", "node-d", { size: 1.5, color: "#2E4D6E" });
graph.addEdge("node-c", "node-d", { size: 1.5, color: "#2E4D6E" });

第 3 步：实例化 Sigma 渲染器并完成画面挂载

有了数据对象和 DOM 容器之后，只需一行代码调用 new Sigma(graph, container, [options])，引擎就会自动初始化 WebGL 上下文、创建着色器缓冲区并把网络图完整呈现出来。

// 获取 DOM 挂载点
const container = document.getElementById("sigma-container");

// 初始化渲染器
const renderer = new Sigma(graph, container, {
  renderEdgeLabels: true,       // 允许渲染边标签（需 edgeLabel 属性）
  defaultNodeColor: "#83ADD0",  // 缺省节点颜色
  defaultEdgeColor: "#2E4D6E",  // 缺省连线颜色
});

第 4 步：注册基础交互与相机控制

sigma.js 内置了强大的事件监听与相机控制体系。例如，你可以监听节点点击事件，并通过相机的动画接口进行平滑聚焦：

// 监听节点点击事件
renderer.on("clickNode", (event) => {
  const nodeId = event.node;
  const nodeLabel = graph.getNodeAttribute(nodeId, "label");
  console.log(`用户选中了节点: [${nodeId}] ${nodeLabel}`);

  // 获取该节点坐标并驱动相机平滑聚焦
  const nodePosition = renderer.getNodeDisplayData(nodeId);
  renderer.getCamera().animate(
    {
      x: nodePosition.x,
      y: nodePosition.y,
      ratio: 0.4, // 放大视角
    },
    { duration: 500 }
  );
});

// 监听鼠标悬浮进入与离开
renderer.on("enterNode", ({ node }) => {
  container.style.cursor = "pointer";
});
renderer.on("leaveNode", () => {
  container.style.cursor = "default";
});

三、React 项目集成：生命周期与资源安全清理

在 React 单页面应用中引入 WebGL 库时，最核心的挑战在于虚拟 DOM 的重新渲染节奏与底层原生 WebGL 上下文生命周期的同步。如果处理不当，每次页面更新都会堆积重复的 Canvas 画布并造成 GPU 内存泄漏。

方案一：轻量直接集成（useRef + useEffect）

如果你的应用追求依赖精简，或者需要对原生 Sigma 实例进行细粒度的自由调优，直接利用 React 基础 Hooks 是最干净透明的做法：

import React, { useEffect, useRef } from "react";
import Graph from "graphology";
import Sigma from "sigma";

export const VanillaNetworkGraph = () => {
  const containerRef = useRef(null);

  useEffect(() => {
    // 1. 确保容器 DOM 已经存在
    if (!containerRef.current) return;

    // 2. 初始化图数据模型
    const graph = new Graph();
    graph.addNode("svc-auth", { label: "鉴权中心", x: 0, y: 0, size: 16, color: "#77B9AE" });
    graph.addNode("svc-user", { label: "用户服务", x: 6, y: 5, size: 12, color: "#83ADD0" });
    graph.addNode("svc-order", { label: "订单服务", x: -6, y: 5, size: 12, color: "#83ADD0" });
    graph.addEdge("svc-auth", "svc-user", { size: 1.5, color: "#2E4D6E" });
    graph.addEdge("svc-auth", "svc-order", { size: 1.5, color: "#2E4D6E" });

    // 3. 实例化 Sigma 并保存渲染器句柄
    const renderer = new Sigma(graph, containerRef.current, {
      allowInvalidContainer: true,
    });

    // 4. 【极度重要】在清理函数中销毁 WebGL 上下文与事件监听
    return () => {
      renderer.kill();
      graph.clear();
    };
  }, []); // 依赖项设为空数组，确保单例挂载

  return (
    <div
      ref={containerRef}
      style={{
        width: "100%",
        height: "560px",
        background: "#142537",
        borderRadius: "8px",
      }}
    />
  );
};

方案二：使用官方生态库 @react-sigma/core

如果希望以声明式 JSX 组件的形式开发，可以选用官方生态维护的封装库 @react-sigma/core。它内置了上下文 Provider 与常用的控制器组件：

npm install graphology sigma @react-sigma/core

使用方式如下：

import React, { useMemo } from "react";
import Graph from "graphology";
import { SigmaContainer, ControlsContainer, ZoomControl, FullScreenControl } from "@react-sigma/core";
import "@react-sigma/core/lib/react-sigma.min.css";

export const ReactSigmaGraph = () => {
  // 使用 useMemo 构建图拓扑，避免组件重渲染时反复重算
  const graph = useMemo(() => {
    const g = new Graph();
    g.addNode("cluster-1", { label: "华东节点", x: 0, y: 0, size: 15, color: "#77B9AE" });
    g.addNode("cluster-2", { label: "华南节点", x: 8, y: 6, size: 12, color: "#83ADD0" });
    g.addEdge("cluster-1", "cluster-2", { size: 2, color: "#2E4D6E" });
    return g;
  }, []);

  return (
    <SigmaContainer
      graph={graph}
      style={{ height: "560px", width: "100%", background: "#142537" }}
      settings={{ defaultNodeColor: "#83ADD0" }}
    >
      <ControlsContainer position="top-right">
        <ZoomControl />
        <FullScreenControl />
      </ControlsContainer>
    </SigmaContainer>
  );
};

四、选型对比与排障全景矩阵

为了帮助读者根据实际项目规模进行理性选型，并能够从容排查初次绘制时可能碰到的各种异常，下表梳理了原生方案与 React 生态方案的差异，并辅以排障自查矩阵：

五、总结与进阶建议

通过本文的讲解与实践，我们掌握了 sigma.js 在原生 JavaScript 与 React 双栈下的标准起步方法：

1. 牢记架构解耦：图数据属于 graphology，渲染视图属于 sigma.js。一切数据增删改查直接在 Graph 实例上操作，引擎会自动响应。
2. 保障基础要素：容器必须具备确定的 CSS 高宽像素值，节点必须提供有效的数值型 x 与 y 坐标。
3. 时刻注意资源释放：在 React 等 SPA 环境中，务必在组件销毁钩子中执行 renderer.kill()，防止 WebGL 上下文积累泄漏。

当你的首个网络图顺利呈现之后，你可以进一步深入 sigma.js 的高级特性，例如编写自定义 WebGL 程序（Custom Program）实现发光脉冲连线、节点动态水波纹动画，或接入数万级节点的力导向 WebWorker 实时计算，充分释放现代浏览器的硬件加速潜力。