怎么使用 D3.js v7 绘制交互式力导向图

一、核心机制：力导向图是如何运转的

力导向图（Force-Directed Graph）本质上是一个粒子物理仿真系统。在图结构中，每个实体被称为“节点（Node）”，实体之间的关联被称为“连线（Link）”。如果只根据原始数据绘制，节点会由于缺乏位置信息全部堆叠在画布原点。

D3.js v7 解决这一问题的方式是内置的 d3-force 模块。该模块把每个节点视为物理空间中的质点，赋予它们初始坐标 (x, y) 和初速度 (vx, vy)。随后，引擎会在每个离散的时间步长（Tick）中综合计算每个节点受到的合力，计算出加速度并更新速度与位置，直到整体系统能量衰减至平衡状态。

在仿真执行过程中，引擎内部维护一个名为 alpha（能量值）的衰减参数。初始化时 alpha 默认为 1，随迭代逐步向 alphaMin（默认为 0.001）衰减。当 alpha < alphaMin 时，仿真停止计算，图表在视觉上固定就位，从而避免不必要的 CPU 消耗。

二、操作步骤：五步绘制交互式力导向图

使用 D3.js v7 绘制交互式力导向图，可以划分为 5 个清晰的开发阶段：

第 1 步：准备标准的数据结构

D3 力导向图需要两组基础数组：节点数组 nodes 与连线数组 links。在初始定义时，连线的 source 和 target 通常指定为节点的唯一 ID 字符串：

const nodes = [
  { id: "研发中心", group: 1, radius: 25 },
  { id: "前端组", group: 1, radius: 18 },
  { id: "后端组", group: 1, radius: 18 },
  { id: "设计组", group: 2, radius: 18 },
  { id: "产品组", group: 2, radius: 18 }
];

const links = [
  { source: "研发中心", target: "前端组", value: 3 },
  { source: "研发中心", target: "后端组", value: 3 },
  { source: "研发中心", target: "设计组", value: 1 },
  { source: "设计组", target: "产品组", value: 2 },
  { source: "前端组", target: "设计组", value: 2 }
];

第 2 步：初始化物理仿真器

通过调用 d3.forceSimulation(nodes) 创建仿真实例，并依次链式挂载所需的物理力约束：

const width = 800;
const height = 500;

const simulation = d3.forceSimulation(nodes)
  // 1. 弹簧连线力：指定 links 数组并通过 .id() 告诉 D3 如何匹配节点
  .force("link", d3.forceLink(links).id(d => d.id).distance(90))
  // 2. 多体引力/排斥力：负值表示彼此排斥
  .force("charge", d3.forceManyBody().strength(-240))
  // 3. 重心牵引力：将整个网络居中在视口中心
  .force("center", d3.forceCenter(width / 2, height / 2))
  // 4. 碰撞保护力：以节点半径 + 额外间距作为边界，防止重叠
  .force("collision", d3.forceCollide().radius(d => d.radius + 6));

第 3 步：创建 SVG 图元并绑定数据

在 SVG 绘图中，元素的堆叠次序遵循“后绘制者居上”的规则。因此必须先绘制底层的连线，再绘制节点圆圈，最后绘制文字标签：

const svg = d3.select("#chart")
  .append("svg")
  .attr("viewBox", [0, 0, width, height])
  .attr("width", "100%")
  .attr("height", height);

// 创建主容器组，以便支持整体平移与缩放
const g = svg.append("g");

// 绘制连线
const link = g.append("g")
  .attr("stroke", "#CBD5E1")
  .attr("stroke-opacity", 0.8)
  .selectAll("line")
  .data(links)
  .join("line")
  .attr("stroke-width", d => Math.sqrt(d.value) * 2);

// 绘制节点容器
const node = g.append("g")
  .selectAll("g")
  .data(nodes)
  .join("g");

// 节点圆形
node.append("circle")
  .attr("r", d => d.radius)
  .attr("fill", d => d.group === 1 ? "#6487A5" : "#C28B68")
  .attr("stroke", "#FFFFFF")
  .attr("stroke-width", 2);

// 节点文字
node.append("text")
  .text(d => d.id)
  .attr("text-anchor", "middle")
  .attr("dy", ".35em")
  .attr("font-size", "12px")
  .attr("fill", "#FFFFFF")
  .style("pointer-events", "none");

第 4 步：通过 Tick 监听器更新坐标

物理仿真器会在每个计算帧触发 tick 事件。我们需要在回调函数中把 D3 计算出来的 d.x 和 d.y 赋给对应的 DOM 属性：

simulation.on("tick", () => {
  // 更新连线两端点坐标
  link
    .attr("x1", d => d.source.x)
    .attr("y1", d => d.source.y)
    .attr("x2", d => d.target.x)
    .attr("y2", d => d.target.y);

  // 更新节点组位置
  node
    .attr("transform", d => `translate(${d.x}, ${d.y})`);
});

三、交互实现：节点拖拽与画布缩放

静态力导向图只能用于展示最终平衡形态。要让图表真正具有交互性，关键在于实现节点的鼠标拖拽与画布的平移缩放。

1. 节点拖拽实现与原理解析

在 D3 中，如果节点对象拥有 fx 和 fy 属性（Fixed X / Fixed Y），物理引擎就会在每次迭代时无条件将节点钉在该位置，忽略其它力的拉扯。利用这一特性，我们可以构造完整的拖拽行为：

function drag(simulation) {
  function dragstarted(event, d) {
    // 如果只有当前操作，提升系统的 alpha 目标值并重启仿真，使周围节点产生连联动效
    if (!event.active) simulation.alphaTarget(0.3).restart();
    d.fx = d.x;
    d.fy = d.y;
  }

  function dragged(event, d) {
    // 鼠标移动时，不断更新锁定坐标为当前光标位置
    d.fx = event.x;
    d.fy = event.y;
  }

  function dragended(event, d) {
    // 拖拽释放后，将 alphaTarget 归零，允许物理引擎逐渐平息停机
    if (!event.active) simulation.alphaTarget(0);
    // 业务选择：如果希望松手后自由反弹，设为 null；如果希望固定在松手位置，则保留 d.fx/fy
    d.fx = null;
    d.fy = null;
  }

  return d3.drag()
    .on("start", dragstarted)
    .on("drag", dragged)
    .on("end", dragended);
}

// 应用到节点组
node.call(drag(simulation));

2. 画布缩放与平移 (Zoom & Pan)

关系网络节点较多时，容易超出视口范围。通过 d3.zoom() 可以极少代码为整个画布添加平移与滚轮缩放功能：

const zoom = d3.zoom()
  .scaleExtent([0.2, 4]) // 限制缩放比例在 0.2 倍至 4 倍之间
  .on("zoom", (event) => {
    // 将缩放矩阵应用到最外层的内容容器 g 上
    g.attr("transform", event.transform);
  });

svg.call(zoom);

四、完整可运行示例

以下是整合了上述全部逻辑的单文件完整代码。保存为 .html 文件后在任何现代浏览器中双击即可直接运行：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>D3.js v7 交互式力导向图示例</title>
  <script src="https://d3js.org/d3.v7.min.js"></script>
  <style>
    body { margin: 0; background-color: #FAFAF7; font-family: sans-serif; }
    #chart { width: 100vw; height: 100vh; overflow: hidden; }
    .node-label { pointer-events: none; user-select: none; }
  </style>
</head>
<body>
  <div id="chart"></div>

  <script>
    const width = window.innerWidth;
    const height = window.innerHeight;

    // 1. 数据集定义
    const nodes = [
      { id: "平台系统", group: 1, r: 28 },
      { id: "认证服务", group: 1, r: 20 },
      { id: "网关集群", group: 1, r: 22 },
      { id: "数据库", group: 2, r: 24 },
      { id: "缓存节点", group: 2, r: 18 },
      { id: "监控探针", group: 3, r: 16 }
    ];

    const links = [
      { source: "平台系统", target: "认证服务", value: 2 },
      { source: "平台系统", target: "网关集群", value: 4 },
      { source: "网关集群", target: "认证服务", value: 2 },
      { source: "认证服务", target: "数据库", value: 3 },
      { source: "网关集群", target: "缓存节点", value: 3 },
      { source: "平台系统", target: "监控探针", value: 1 }
    ];

    // 2. 准备 SVG 容器与缩放
    const svg = d3.select("#chart")
      .append("svg")
      .attr("viewBox", [0, 0, width, height])
      .attr("width", width)
      .attr("height", height);

    const g = svg.append("g");

    svg.call(d3.zoom()
      .scaleExtent([0.3, 3])
      .on("zoom", (event) => g.attr("transform", event.transform)));

    // 3. 构建力仿真引擎
    const simulation = d3.forceSimulation(nodes)
      .force("link", d3.forceLink(links).id(d => d.id).distance(100))
      .force("charge", d3.forceManyBody().strength(-300))
      .force("center", d3.forceCenter(width / 2, height / 2))
      .force("collision", d3.forceCollide().radius(d => d.r + 5));

    // 4. 渲染图元
    const link = g.append("g")
      .attr("stroke", "#CBD5E1")
      .attr("stroke-opacity", 0.7)
      .selectAll("line")
      .data(links)
      .join("line")
      .attr("stroke-width", d => d.value * 1.5);

    const node = g.append("g")
      .selectAll("g")
      .data(nodes)
      .join("g")
      .call(d3.drag()
        .on("start", (event, d) => {
          if (!event.active) simulation.alphaTarget(0.3).restart();
          d.fx = d.x;
          d.fy = d.y;
        })
        .on("drag", (event, d) => {
          d.fx = event.x;
          d.fy = event.y;
        })
        .on("end", (event, d) => {
          if (!event.active) simulation.alphaTarget(0);
          d.fx = null;
          d.fy = null;
        }));

    node.append("circle")
      .attr("r", d => d.r)
      .attr("fill", d => d.group === 1 ? "#6487A5" : d.group === 2 ? "#C28B68" : "#94A3B8")
      .attr("stroke", "#FFFFFF")
      .attr("stroke-width", 2.5);

    node.append("text")
      .attr("class", "node-label")
      .text(d => d.id)
      .attr("text-anchor", "middle")
      .attr("dy", ".35em")
      .attr("fill", "#FFFFFF")
      .attr("font-size", "12px");

    // 5. 每帧同步
    simulation.on("tick", () => {
      link
        .attr("x1", d => d.source.x)
        .attr("y1", d => d.source.y)
        .attr("x2", d => d.target.x)
        .attr("y2", d => d.target.y);

      node
        .attr("transform", d => `translate(${d.x}, ${d.y})`);
    });
  </script>
</body>
</html>

五、参数调优与常见问题排查

在实际开发过程中，初学者经常会遇到节点重叠、连线报错或动画卡顿等现象。以下是力导向图开发中最常见的四类问题及其解决方式：

核心参数调节参考表

六、总结

掌握 D3.js v7 力导向图的关键在于理清“物理仿真计算”与“SVG 视觉渲染”两套体系的协作机制。d3.forceSimulation 只负责纯粹的坐标数值运算，并通过 tick 事件驱动将位置投射给 SVG 的 circle 和 line。通过合理配置多体斥力、连线弹簧、重心引导与碰撞检测，配合 alphaTarget 驱动的状态机交互，即可在网页端高效呈现生动且稳定的网络拓扑关系。