sigma.js 相机控制：实现程序化缩放和平移视图的方法

一、认识 sigma.js 相机模型与坐标系统

sigma.js 专为大规模图网络设计，采用 WebGL 负责底层高效渲染。与直接修改 DOM 节点不同，图形渲染中所有的节点与边均固定在 Graphology 图数据模型定义的绝对坐标系内。当用户在屏幕上拖拽平移或缩放画面时，图网络内部节点的数据坐标（例如 node.x 与 node.y）并不会发生任何改变。

实现画面移动和缩放的实体是相机（Camera）。相机本质上是一组投影矩阵变换器，负责将图数据空间内的几何图形投射到 HTML 容器的像素视口中。程序化控制视图，就是在代码中动态修改相机的观察参数。

1. 相机的四个核心状态属性

通过 camera.getState() 可以读取当前相机的几何状态对象，该对象包含四个核心属性：

2. 屏幕像素与图坐标的转换方法

在处理点击事件、外部悬浮菜单定位或视口测量时，常常需要进行坐标换算。sigma.js 渲染器提供了两个内建转换函数：

• renderer.viewportToGraph({ x, y })：将屏幕 DOM 像素坐标（如鼠标点击的 e.clientX 对应容器内的偏移）转换为图空间的实际坐标。
• renderer.graphToViewport({ x, y })：将图空间中某个节点的坐标转换为当前屏幕上的像素坐标，用于精确定位 HTML 浮层或 Tooltip。

二、程序化控制相机的实现步骤

无论是编写自定义缩放按钮、实现图搜索对焦，还是在布局算法运行完毕后自适应居中，程序化调用均遵循一套标准时序。

步骤 1：获取相机控制器实例

在完成 sigma.js 渲染器实例化后，可通过 renderer.getCamera() 直接获取单例相机对象：

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

// 初始化容器与图数据
const container = document.getElementById("sigma-container");
const graph = new Graph();
// ...加载节点与边数据...

// 实例化渲染器并获取相机
const renderer = new Sigma(graph, container);
const camera = renderer.getCamera();

步骤 2：解算目标状态参数

根据业务场景，确定相机需要达到的目标状态。目标状态可以是一个包含完整 { x, y, ratio, angle } 的对象，也可以仅包含需要变更的属性（例如只改变缩放比率 { ratio: 0.2 }，未指定的属性将保持当前相机的实际值不变）：

// 示例：仅将视口中心平移至目标位置，保持现有缩放比例不变
const targetState = {
  x: 0.35,
  y: 0.42
};

步骤 3：选择调用方式（瞬时生效 vs 平滑动画）

sigma.js 提供了两类控制方法，分别适用于不同的人机交互需求：

• 瞬时生效（camera.setState）：视口无过渡直接跳变至目标值。适合在初始化场景、重置布局或不需要视觉过渡的后台批处理中使用。

  // 瞬时生效，无动画过渡
  camera.setState({
    x: 0.5,
    y: 0.5,
    ratio: 1.0,
    angle: 0
  });

• 平滑动画（camera.animate）：启动内置缓动插值器，在指定时间内按指定动画曲线平滑推进视口。适合节点聚焦、按钮点击缩放等需要良好用户体验的场景。

  // 平滑过渡动画
  camera.animate(
    { x: 0.35, y: 0.42, ratio: 0.25 },
    {
      duration: 600,            // 动画时长（毫秒）
      easing: "quadraticInOut"  // 缓动曲线类型
    }
  );

步骤 4：监听渲染更新与回调处理

在执行 camera.animate() 时，如果需要知道动画何时结束以便执行后续操作（例如弹出详情弹窗、高亮关联边），可以直接传入完成回调，或监听相机的 updated 事件：

// 方式 A：使用回调函数（支持在动画结束后触发业务逻辑）
camera.animate(
  { x: 0.2, y: 0.3, ratio: 0.3 },
  { duration: 500 },
  () => {
    console.log("视口平移与缩放动画已完成，可显示节点详细信息浮层");
  }
);

// 方式 B：监听相机的通用状态更新事件
camera.on("updated", (state) => {
  // 每一帧矩阵更新或动画插值推进时均会触发
});

三、常见业务场景与完整代码实现

针对实际项目中最常遇到的四类控制需求，以下分别提供直接可用的完整实现方案。

1. 聚焦并放大到指定节点（Focus on Node）

在节点搜索、拓扑下钻或点击列表项时，需要视口自动移动到对应节点，并放大以看清该节点的关联拓扑：

/**
 * 视口平滑聚焦到指定节点
 * @param {Sigma} renderer - sigma 渲染器实例
 * @param {string} nodeId - 目标节点唯一标识
 * @param {number} zoomRatio - 目标缩放比例，默认 0.15（特写级别）
 */
function focusOnNode(renderer, nodeId, zoomRatio = 0.15) {
  const graph = renderer.getGraph();
  if (!graph.hasNode(nodeId)) {
    console.warn(`节点 ${nodeId} 不存在于当前图谱中`);
    return;
  }

  // 1. 读取节点在图空间中的真实坐标
  const nodeAttributes = graph.getNodeAttributes(nodeId);
  const camera = renderer.getCamera();

  // 2. 调度平滑过渡
  camera.animate(
    {
      x: nodeAttributes.x,
      y: nodeAttributes.y,
      ratio: zoomRatio
    },
    {
      duration: 600,
      easing: "quadraticInOut"
    }
  );
}

2. 工具栏步进放大与缩小（Zoom In / Out）

除了通用的 animate 之外，sigma.js 相机还内置了专用的步进式缩放快捷函数：camera.animatedZoom() 与 camera.animatedUnzoom()。它们以当前视口中心为基准点，按比例扩大或收缩视野：

// 绑定工具栏放大按钮 [+]
document.getElementById("btn-zoom-in").addEventListener("click", () => {
  // factor 默认为 1.5，表示将视野放大 1.5 倍（即 ratio 变为原本的 1 / 1.5）
  camera.animatedZoom({
    duration: 300,
    factor: 1.4
  });
});

// 绑定工具栏缩小按钮 [-]
document.getElementById("btn-zoom-out").addEventListener("click", () => {
  // 将视野缩小（即 ratio 变为原本的 1 * 1.4）
  camera.animatedUnzoom({
    duration: 300,
    factor: 1.4
  });
});

3. 全图 / 多节点自适应视口居中（Fit to View）

当导入新数据、切换过滤条件或运行完力导向布局后，节点可能分布在不同的范围，此时需要自动调整相机中心与 ratio，使全部节点或选中的子网络完整居中显示在屏幕内：

/**
 * 计算多个节点的包围盒并自适应撑满视口
 * @param {Sigma} renderer - sigma 渲染器实例
 * @param {string[]} [nodeIds] - 可选，指定节点 ID 列表。若不传则默认为全部节点
 * @param {number} [padding] - 边缘留白安全边距比例，默认 0.15（留出 15% 边距）
 */
function fitNodesToView(renderer, nodeIds, padding = 0.15) {
  const graph = renderer.getGraph();
  const targetNodes = nodeIds || graph.nodes();

  if (targetNodes.length === 0) return;

  // 1. 遍历计算目标节点集合的最小/最大坐标 (Bounding Box)
  let minX = Infinity, maxX = -Infinity;
  let minY = Infinity, maxY = -Infinity;

  targetNodes.forEach((nodeKey) => {
    const { x, y } = graph.getNodeAttributes(nodeKey);
    if (x < minX) minX = x;
    if (x > maxX) maxX = x;
    if (y < minY) minY = y;
    if (y > maxY) maxY = y;
  });

  // 2. 解算几何中心
  const centerX = (minX + maxX) / 2;
  const centerY = (minY + maxY) / 2;

  // 3. 计算包围盒跨度并预留边缘留白
  const spanX = Math.max(maxX - minX, 0.001) * (1 + padding * 2);
  const spanY = Math.max(maxY - minY, 0.001) * (1 + padding * 2);

  // 4. 根据容器宽高比换算合适 ratio
  // 在 sigma 中，ratio 为 1.0 时对应图空间跨度大致为 1.0 左右的视野
  const targetRatio = Math.max(spanX, spanY);

  // 5. 平滑过渡到居中自适应视角
  renderer.getCamera().animate(
    {
      x: centerX,
      y: centerY,
      ratio: targetRatio
    },
    {
      duration: 600,
      easing: "quadraticInOut"
    }
  );
}

4. 视角一键复位（Reset View）

当用户在自由探索中旋转或过度缩放视口后，通常需要一个复位按钮将相机还原至系统默认的几何原点：

// 绑定复位按钮 [Reset]
document.getElementById("btn-reset-view").addEventListener("click", () => {
  // animatedReset 会将 x=0.5, y=0.5, ratio=1.0, angle=0 统一恢复
  camera.animatedReset({
    duration: 500
  });
});

四、进阶调优与注意事项

在实际生产环境中运用相机控制时，如果忽视 WebGL 渲染并发性与坐标系约束，可能会出现动画闪烁、视角漂移或性能卡顿等问题。以下是四点核心工程实践规范：

1. 连击打断与动画覆盖策略

当用户快速连续点击放大按钮或切换搜索选项时，会频繁调用 camera.animate()。sigma.js 的相机内部自带冲突保护机制：每次调用新的 animate() 时，会自动终止上一段未执行完的动画，并从当前的实时相机状态无缝过渡至新目标。

尽管如此，对于高频输入的 UI 控件，仍建议在前端业务层加入 100~150ms 的防抖或节流（Debounce / Throttle），避免不必要的矩阵计算开销。

2. 防止缩放越界的极值保护（Ratio Clamping）

在程序化计算目标 ratio 时，务必对数值范围进行边界限制。若 ratio 计算结果接近 0，视口会放大到微米级别，导致图谱节点全部飞出屏幕；若 ratio 异常巨大，图谱将缩小成肉眼不可见的单个像素点：

// 设定合理的缩放安全上下限
const MIN_RATIO = 0.02; // 最大放大倍数
const MAX_RATIO = 5.0;  // 最大缩小倍数

function safeZoom(camera, newRatio) {
  const clampedRatio = Math.min(Math.max(newRatio, MIN_RATIO), MAX_RATIO);
  camera.animate({ ratio: clampedRatio }, { duration: 300 });
}

3. 正确区分图论坐标与渲染显示坐标

在 Graphology 图数据中，节点的属性 x 和 y 代表其在图空间内的抽象拓扑坐标；而 renderer.getNodeDisplayData(nodeId) 返回的是经过归一化渲染处理器修饰后的显示数据。在进行相机定位时，应统一以图空间原始坐标或 graph.getNodeAttributes() 为基准，不要混用未经换算的屏幕像素值。

4. 程序化控制与手势交互的协同

sigma.js 允许程序化相机动画与用户的鼠标拖拽、滚轮缩放并存。在动画进行期间，如果用户突然用鼠标拖拽了画布，默认行为是用户的手势输入会立即接管相机控制权，动画自然过渡为手动平移。这种非阻塞设计符合直觉，开发者无需在调用 camera.animate() 时手动禁用容器的鼠标监听。

五、总结

实现 sigma.js 相机程序化缩放和平移的核心脉络可以总结为以下要点：

1. 识别控制核心：一切视口变换均由 renderer.getCamera() 返回的单例相机驱动，图网络底层数据始终保持静止。
2. 理解四维状态：视口中心 (x, y) 决定平移位置，ratio 决定缩放视野大小（反比关系），angle 决定旋转方位。
3. 按需选用模式：即时切换用 camera.setState()，视觉过渡用 camera.animate()，单步缩放用 camera.animatedZoom() 与 camera.animatedUnzoom()。
4. 注重工程防御：在复杂应用中加入边界约束（Min/Max Ratio）与坐标系校验，确保图可视化界面在任何交互下都保持稳定流畅。