sigma.js 自定义节点样式：设置颜色、大小及标签显示的技巧

一、图数据建模：在 Graphology 中规范节点基准属性

现代 sigma.js 彻底剥离了内部图拓扑存储逻辑，全面依赖 graphology 库作为数据内核。在初始化节点样式前，必须明确 sigma.js 渲染器默认识别的核心视觉属性。每个节点在进入渲染管线前，都需要具备以下几何与标识字段：

• x 与 y：节点在二维平面上的绝对坐标。建议在数据录入前通过力导向算法（如 ForceAtlas2）或归一化工具将坐标映射至均匀空间，避免节点聚集在局部狭小区域。
• size：节点的基准绘制半径。此数值为虚拟图空间度量，在进入视口时会乘以相机的投影缩放比（camera.ratio）。
• color：节点的默认颜色，支持标准的 Hex 字符串（如 #345E82）或 RGB 格式。
• label：节点所绑定的文本标签。若未定义，该节点在 Canvas 标签层中将被跳过。

向数据层注入初始节点属性的代码示例如下：

import Graph from "graphology";

const graph = new Graph();

// 声明节点基础属性：存储静态度量与基准外观
graph.addNode("user_101", {
  x: 12.5,
  y: -45.2,
  size: 8,
  color: "#345E82",
  label: "核心枢纽节点 A",
  // 额外挂载业务度量属性（供后续动态计算使用）
  degree: 142,
  category: "core"
});

二、标准实施流程：从静态定义到动态渲染的四步法

为了实现高效、无卡顿的自定义样式，必须遵循规范的工程流程。图 1 展示了在 sigma.js 中实现完整节点样式自定义的标准流水线：

该工作流明确划分了职责范围：第一步完成静态属性建模；第二步通过状态机驱动纯函数 Reducer；第三步设置全局视口裁剪策略；第四步针对特殊图形需求引入着色器。这样不仅结构清晰，而且后续排查视觉渲染 bug 时能够迅速定位环节。

三、节点大小自定义：从度量指标到视觉半径的数学映射

在真实业务图谱中，节点的度数（Degree）或重要性权重往往呈现长尾幂律分布（少数超级节点度数极高，绝大多数边缘节点度数很低）。如果采用简单的线性映射公式：

// 不推荐：线性映射在长尾数据中表现极差
size = minSize + (degree / maxDegree) * (maxSize - minSize);

这会导致除前几个超级节点外，其余绝大多数节点的尺寸几乎贴紧 minSize，无法形成有效的视觉层次梯队。

1. 对数尺度缩放（Logarithmic Transform）

解决长尾分布的标准解法是对度量取对数。通过对数函数的平缓增长特性，压缩头部超级节点，同时拉伸低度数节点的视觉区分度：

function calculateNodeSize(degree, maxDegree, minSize = 4, maxSize = 24) {
  if (degree <= 0) return minSize;
  // 对数归一化计算
  const ratio = Math.log(degree + 1) / Math.log(maxDegree + 1);
  // 夹紧截断在 [minSize, maxSize] 区间
  return Math.min(maxSize, Math.max(minSize, minSize + ratio * (maxSize - minSize)));
}

2. 视口交互中的尺寸动态缩放

当用户悬停（hover）在某个节点上时，往往希望该节点适度放大以突出焦点。此时切勿调用 graph.setNodeAttribute(node, 'size', newSize)，因为修改底层图数据会引发 Graphology 拓扑变更广播。正确的做法是在 nodeReducer 中动态返回临时放大的尺寸：

// 在 nodeReducer 中动态放大悬停节点
if (node === hoveredNode) {
  res.size = data.size * 1.3; // 局部放大 30%
  res.zIndex = 10;          // 提高渲染层级，确保不被相邻节点覆盖
}

四、节点颜色自定义：分类调色盘与状态驱动的动态着色

在复杂网络分析中，颜色通常承担两种语义职责：一是静态维度（表达社团分类、节点类别或数值区间）；二是动态维度（表达选中、高亮、搜索过滤与失焦淡化）。

1. 离散分类调色盘映射

对于业务类别标签（如角色、机构、部门），应在外部建立映射表，避免在渲染循环中动态拼接颜色字符串：

const CATEGORY_PALETTE = {
  "core": "#345E82",    // 工程蓝：核心主体
  "bridge": "#AD8060",  // 铜棕色：关键桥接中介
  "outlier": "#94A3B8"  // 浅灰板岩：外围叶子节点
};

// 遍历赋予初始颜色
graph.forEachNode((node, attributes) => {
  const paletteColor = CATEGORY_PALETTE[attributes.category] || "#64748B";
  graph.setNodeAttribute(node, "color", paletteColor);
});

2. 交互状态降暗（Dimming）实现技巧

在网络图中，“高亮当前节点及其一阶邻居，同时将其余所有无关节点变暗淡化”是最常见且有效的交互模式。利用 nodeReducer 可以在毫秒级完成全图状态更新：

let hoveredNode = null;
let hoveredNeighbors = new Set();

// 绑定 Sigma 的 nodeReducer
sigma.setSetting("nodeReducer", (node, data) => {
  const res = { ...data };

  if (!hoveredNode) {
    // 无悬停状态，返回原始数据
    return res;
  }

  if (node === hoveredNode) {
    res.color = "#AD8060"; // 焦点节点使用强调铜棕色
    res.highlighted = true;
    res.zIndex = 10;
  } else if (hoveredNeighbors.has(node)) {
    res.highlighted = true; // 邻居节点保持原有分类色
    res.zIndex = 5;
  } else {
    // 无关节点统一淡化降噪
    res.color = "#CBD5E1";
    res.label = "";        // 隐藏无关节点标签
    res.zIndex = 0;
  }

  return res;
});

// 监听鼠标进入与离开事件
sigma.on("enterNode", ({ node }) => {
  hoveredNode = node;
  hoveredNeighbors = new Set(graph.neighbors(node));
  sigma.refresh(); // 触发渲染缓冲区更新
});

sigma.on("leaveNode", () => {
  hoveredNode = null;
  hoveredNeighbors.clear();
  sigma.refresh();
});

五、标签显示控制：阈值裁剪、防遮挡与排版优化技巧

文本标签是图可视化中信息传达最直接的通道，但在大数据量下也最容易沦为视觉灾难。如果全量渲染标签，不仅文字会挤成一片漆黑（重叠掩盖），而且还会导致大量的 Canvas fillText 重绘开销。sigma.js 内置了高效的双重过滤机制。

1. 关键配置参数解析

2. 精细化标签显示调优代码

// 在实例化 Sigma 时配置标签引擎
const renderer = new Sigma(graph, container, {
  // 启用标签渲染
  renderLabels: true,

  // 技巧一：节点屏幕像素半径小于 9px 时，绝不渲染标签
  labelRenderedSizeThreshold: 9,

  // 技巧二：优化网格碰撞密度，避免重叠
  labelDensity: 0.07,
  labelGridCellSize: 100,

  // 技巧三：排版字体与字重控制
  labelFont: '-apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif',
  labelSize: 12,
  labelWeight: "500",

  // 技巧四：标签颜色跟随节点自身颜色，保证视觉一致性
  labelColor: {
    mode: "node",
    attribute: "color"
  }
});

六、进阶扩展：自定义 WebGL NodeProgram

sigma.js 默认的节点渲染器是 NodeCircleProgram，它将每个节点渲染为标准的纯色实心圆。如果业务需要更加丰富的视觉表现（例如外层双色边框、内外同心环、圆形头像贴图或状态指示徽标），可以通过注册自定义的 NodeProgram 来实现。

1. 使用官方边框扩展程序

以官方提供的 @sigma/node-border 为例，只需在初始化配置中注册对应的着色器类，即可为节点赋予边框属性：

import { NodeBorderProgram } from "@sigma/node-border";

const renderer = new Sigma(graph, container, {
  // 注册自定义节点着色器程序
  nodeProgramClasses: {
    "bordered": NodeBorderProgram
  },
  // 设置默认渲染器类型
  defaultNodeType: "bordered"
});

// 在数据中指定边框颜色与宽度比例
graph.addNode("vip_node", {
  x: 0,
  y: 0,
  size: 15,
  color: "#F2F6FA",         // 节点内部底色
  borderColor: "#345E82",   // 边框使用主色工程蓝
  borderRatio: 0.2,         // 边框厚度占半径的 20%
  label: "VIP 边框节点",
  type: "bordered"
});

七、技术方案选型与性能调优指南

为了在开发效率与极限性能之间取得平衡，下表对三种主要自定义层级进行了综合对比：

生产环境优化检查清单

1. 避免在 Reducer 内部执行复杂查询：nodeReducer 会在每次视口刷新或 refresh() 时对全图可见节点逐一执行。切勿在 Reducer 中调用 graph.neighbors(node) 或耗时的遍历搜索，悬停邻居集合应提前计算好（例如存入 Set 中），Reducer 内部仅做 $O(1)$ 的成员判断。
2. 合并属性更新调用：如果必须批量初始化或修改节点基础属性，优先使用 graph.updateEachNodeAttributes(...) 或在 graph.batch(() => { ... }) 事务块中进行，避免连续触发成千上万次单独的变更事件。
3. 相机层级联动策略：结合 camera.on('updated', () => { ... }) 监听视口缩放比。当缩放比极小时（全图宏观视角），可通过临时禁用 renderLabels 或将 labelRenderedSizeThreshold 提高至 20，进一步节省 CPU 与 GPU 开销。

总结而言，sigma.js 的节点自定义样式体系兼顾了极致性能与灵活表现。通过在 Graphology 中规范存储基础几何与分类指标、使用 nodeReducer 响应动态交互，并合理调整标签渲染阈值与网格密度，开发者能够轻松构建出兼具高信息密度与流畅体验的专业图可视化应用。