G6 D3Force 力导向布局实战指南：五种基础力、迭代控制与团队聚类案例-平芜编程栈

数据可视化
前端
图表库

【免费下载链接】G6

♾ A Graph Visualization Framework in JavaScript.

项目地址：https://gitcode.com/gh_mirrors/g6/G6

本篇指南系统讲解 G6（@antv/g6）内置的d3-force力导向布局：它基于 d3-force 物理模拟思想，通过引力、斥力、碰撞等力的叠加将图推向能量最小的稳定状态，常用于社交网络、组织架构、知识图谱等需要自动排布节点并支持实时拖拽调整的场景。读完本文，你将掌握五种基础力的作用原理、全套配置参数（含迭代控制与力模型细分项），并能直接落地"防止节点重叠""团队聚类"两类典型实战配置。

概述：为什么选择 D3Force 布局

D3Force 布局的核心思路是把图当作一个物理世界：节点是带有质量的小球，边是连接小球的橡皮筋，系统通过模拟物理力的作用不断调整节点位置，直到整个系统达到能量最小的稳定状态。它的主要特点如下：

自动排列：不需要手动设置节点位置，系统会自动为每个节点找到合适的位置；
实时调整：拖动某个节点时，其他节点会实时跟随调整位置，适合交互式探索；
灵活配置：可以调整节点间的吸引力和排斥力、设置边的理想长度、固定某些重要节点的位置；
动画效果：节点移动时会有平滑动画，让变化过程更自然（在布局调度源码中可以看到animation开启时会基于布局迭代 tick 逐帧更新位置）。

核心概念

力系统（Force System）

D3Force 布局通过同时模拟五种不同的力来驱动布局收敛。可以把它们想象成作用在物理世界中的无形作用力，最终叠加达到平衡：

链接力（Link Force）：相当于在相连节点之间连了一根橡皮筋，把节点拉到合适的距离。橡皮筋的松紧度就是力的强度（strength），理想长度就是设置的distance；
多体力（Many-Body Force）：类似磁铁的效果，让所有节点互相吸引或排斥。强度为负值时节点互相排斥（如同极磁铁），为正值时互相吸引（如异极磁铁），它直接决定了图的疏密程度；
中心力（Center Force）：像一根看不见的绳子把所有节点拴在画布中心，防止节点飘得太远，让整张图保持居中；
碰撞力（Collision Force）：让节点变成有实体大小的小球，节点靠得太近时自动弹开，主要用来防止节点重叠、提高图的可读性；
径向力（Radial Force）：想象有一个看不见的圆环，该力会把节点吸引到圆环上；通过设置圆的半径和力的强度，可以让节点形成漂亮的环形布局。

从源码角度看，G6 在创建布局实例时会为d3-force/d3-force-3d自动注入默认中心点{ x: width / 2, y: height / 2, z: 0 }，并连同画布宽高、节点尺寸一起混入布局配置（见 initGraphLayout 实现）。

迭代系统（Iteration System）

布局计算是一个反复调整的迭代过程，包含两个关键概念：

Alpha 值（活力值）

Alpha 相当于布局的"能量"，决定节点移动的剧烈程度：

初始状态：Alpha = 1，节点移动剧烈；
计算过程：Alpha 值逐渐降低，节点移动变缓；
结束状态：当 Alpha < alphaMin 时，节点停止移动。

迭代次数（Iterations）

控制每次计算时力的作用次数：

作用：值越大，布局越精确，但计算越慢；
调节建议：简单图使用默认值即可；复杂图可以适当增加迭代次数；实时交互场景建议使用较小的迭代次数。

提示：迭代次数（iterations）和活力值（alpha）是相互配合的。增加迭代次数可以让每一步计算更精确，而活力值则控制整体计算的进度。在 G6 的布局调度中，graphLayout方法对带迭代的布局默认执行iterations = 300次tick（无动画时直接返回终态位置），见 runtime/layout.ts。

配置项

在Graph配置的layout字段中声明type: 'd3-force'即可启用，基础配置如下：

属性	描述	类型	默认值	必选
type	布局类型	string	'd3-force'	✓
centerX	布局中心点 x 坐标	number	width / 2
centerY	布局中心点 y 坐标	number	height / 2
centerStrength	中心力强度	number	-
nodeSize	节点大小（直径），用于碰撞检测防止节点重叠	number \| ((node, index, nodes) => number)	10
nodeSpacing	节点间额外间距	number \| ((node, index, nodes) => number)	0
iterations	力的迭代次数，值越大布局越精确但性能消耗越大	number	-
onTick	每次迭代的回调函数，用于实时获取布局结果	(data: LayoutMapping) => void	-
forceSimulation	自定义力模拟方法，若不指定则使用 d3.js 的方法	Simulation<NodeDatum, EdgeDatum>	-
randomSource	用于生成随机数的函数	() => number	-

其中nodeSize与nodeSpacing都支持传函数（(node, index, nodes) => number），可以为不同节点定制不同大小。G6 在初始化布局时会自动根据节点元素的实际size计算nodeSize（见 initGraphLayout 中的 nodeSize 推导）。

迭代控制

属性	描述	类型	默认值
alpha	当前迭代的收敛阈值，控制布局的活跃程度	number	1
alphaMin	停止迭代的最小阈值，当 alpha 小于该值时停止迭代	number	0.001
alphaDecay	收敛阈值的衰减率，范围 [0, 1]，0.028 对应约 300 次迭代	number	0.028
alphaTarget	目标收敛阈值，系统会尝试将 alpha 收敛到该值	number	0
velocityDecay	速度衰减因子，值越大节点运动越缓慢	number	0.4

力模型配置

链接力（link）

属性	描述	类型	默认值
link.id	边的 id 生成函数	(edge, index, edges) => string	(e) => e.id
link.distance	理想边长，边会趋向于该长度	number \| ((edge, index, edges) => number)	30
link.strength	力的强度，值越大边长越接近理想边长	number \| ((edge, index, edges) => number)	1
link.iterations	链接力的迭代次数	number	1

多体力（manyBody）

属性	描述	类型	默认值
manyBody.strength	力的强度，负值为斥力，正值为引力	number \| ((node, index, nodes) => number)	-30
manyBody.theta	Barnes-Hut 算法的精度参数，值越小越精确但性能消耗越大	number	0.9
manyBody.distanceMin	最小作用距离，防止力过大	number	1
manyBody.distanceMax	最大作用距离，超过该距离的节点不产生力	number	Infinity

中心力（center）

属性	描述	类型	默认值
center.x	中心点 x 坐标	number	-
center.y	中心点 y 坐标	number	-
center.strength	力的强度，值越大节点越趋向于中心点	number	-

补充：5.1 版本中推荐优先使用centerX/centerY作为快捷配置；如果直接配置centerforce，则按 d3-force 原生写法生效。

碰撞力（collide）

属性	描述	类型	默认值
collide.radius	碰撞半径，小于该距离的节点会产生排斥力	number \| ((node, index, nodes) => number)	10
collide.strength	力的强度，值越大排斥效果越明显	number	1
collide.iterations	碰撞检测的迭代次数	number	1

径向力（radial）

属性	描述	类型	默认值
radial.strength	力的强度，值越大节点越趋向于目标半径	number \| ((node, index, nodes) => number)	0.1
radial.radius	目标半径，节点会被吸引到该半径的圆周上	number \| ((node, index, nodes) => number)	100
radial.x	圆心 x 坐标	number	0
radial.y	圆心 y 坐标	number	0

X 轴力（x）

属性	描述	类型	默认值	必选
x.strength	X 轴方向的力强度	number \| ((node, index, nodes) => number)	-
x.x	目标 x 坐标，节点会被吸引到这个位置	number \| ((node, index, nodes) => number)	-

Y 轴力（y）

属性	描述	类型	默认值	必选
y.strength	Y 轴方向的力强度	number \| ((node, index, nodes) => number)	-
y.y	目标 y 坐标，节点会被吸引到这个位置	number \| ((node, index, nodes) => number)	-

源码视角：布局调度与实时拖拽

理解 D3Force 在 G6 中的运行方式，有助于把上述参数用得更准：

布局注册与类型定义：d3-force属于内置布局，其类型在 layouts/types.ts 中定义为D3ForceLayout（type: 'd3-force'），并与d3-force3d一起出现在内置布局联合类型中。
迭代驱动渲染：开启animation后，runtime/layout.ts 会通过onTick回调逐帧把最新位置写入模型并重绘元素（updateElementPosition），这就是"节点移动时平滑动画"的底层实现；关闭动画时则直接tick(iterations)得到终态。
拖拽实时调整：配合内置行为drag-element-force，拖动节点后其他节点会实时跟随。其实现会找到d3-force/d3-force-3d布局实例，在拖拽时调用simulation.alphaTarget(0.3).restart()让模拟器重新活跃起来，松手后再将alphaTarget归零，见 drag-element-force.ts。这正对应文档中"实时调整"特性的实现细节。

仓库内还提供了多个可直接运行的配套示例，可作为调参参考：layout-force.ts（基础力导向）、layout-force-collision.ts（碰撞防重叠）、layout-force-lattice.ts（网格约束力导向）。

代码示例

防止节点重叠

通过为每个节点指定碰撞半径，即可在布局过程中避免节点互相压盖：

{ layout: { type: 'd3-force', collide: { // Prevent nodes from overlapping by specifying a collision radius for each node. radius: (d) => d.size / 2, }, }, }

这里radius使用了函数形式，按每个节点的实际size动态计算碰撞半径，比固定值更贴合节点大小不一的场景。

团队聚类布局

下面的完整示例展示了如何使用力导向布局实现团队聚类：同一团队的节点自动聚集，不同团队之间保持距离。核心技巧是通过link.distance/link.strength的函数形式，让"团队内连接更短更紧、团队间连接更长更松"。

import { Graph } from '@antv/g6'; const graph = new Graph({ container: 'container', width: 500, height: 250, autoFit: 'view', data: { nodes: [ // 团队 A { id: 'A1', team: 'A', label: 'A1', size: 30 }, { id: 'A2', team: 'A', label: 'A2', size: 20 }, { id: 'A3', team: 'A', label: 'A3', size: 20 }, { id: 'A4', team: 'A', label: 'A4', size: 20 }, // 团队 B { id: 'B1', team: 'B', label: 'B1', size: 30 }, { id: 'B2', team: 'B', label: 'B2', size: 20 }, { id: 'B3', team: 'B', label: 'B3', size: 20 }, { id: 'B4', team: 'B', label: 'B4', size: 20 }, // 团队 C { id: 'C1', team: 'C', label: 'C1', size: 30 }, { id: 'C2', team: 'C', label: 'C2', size: 20 }, { id: 'C3', team: 'C', label: 'C3', size: 20 }, { id: 'C4', team: 'C', label: 'C4', size: 20 }, ], edges: [ // 团队 A 内部连接 { source: 'A1', target: 'A2' }, { source: 'A1', target: 'A3' }, { source: 'A1', target: 'A4' }, // 团队 B 内部连接 { source: 'B1', target: 'B2' }, { source: 'B1', target: 'B3' }, { source: 'B1', target: 'B4' }, // 团队 C 内部连接 { source: 'C1', target: 'C2' }, { source: 'C1', target: 'C3' }, { source: 'C1', target: 'C4' }, // 团队间的少量连接 { source: 'A1', target: 'B1' }, { source: 'B1', target: 'C1' }, ], }, node: { style: { size: (d) => d.size, fill: (d) => { // 不同团队使用不同颜色 const colors = { A: '#FF6B6B', B: '#4ECDC4', C: '#45B7D1', }; return colors[d.team]; }, labelText: (d) => d.label, labelPlacement: 'center', labelFill: '#fff', }, }, edge: { style: { stroke: '#aaa', }, }, layout: { type: 'd3-force', // 配置链接力 - 团队内部节点更靠近 link: { distance: (d) => { // 同一团队内的连接距离更短 if (d.source.team === d.target.team) return 50; // 不同团队间的连接距离更长 return 200; }, strength: (d) => { // 同一团队内的连接强度更大 if (d.source.team === d.target.team) return 0.7; // 不同团队间的连接强度更小 return 0.1; }, }, // 配置多体力 - 控制节点间的排斥力 manyBody: { strength: (d) => { // 团队领导节点（编号1）的排斥力更强 if (d.label.endsWith('1')) return -100; return -30; }, }, // 配置碰撞力 - 防止节点重叠 collide: { radius: 35, strength: 0.8, }, // 配置中心力 - 保持图形在画布中心 center: { strength: 0.05, }, }, behaviors: ['drag-element-force'], }); graph.render();

主要配置说明：

link.distance：团队内部距离短（50），团队间距离长（200），实现"物以类聚"；
link.strength：团队内部连接强度大（0.7），团队间连接强度小（0.1），让同团队节点更紧凑；
manyBody.strength：控制节点间的排斥力，团队领导节点（编号 1）设置更强的斥力（-100），使其在团队中占据更中心、更开阔的位置；
collide：radius: 35配合strength: 0.8防止节点重叠；
center：strength: 0.05让整体布局稳定在画布中心；
behaviors: ['drag-element-force']：启用拖拽实时调整，拖动任意节点时全图会重新收敛。

若需要为不同节点定制完全不同的力参数（如按节点分组设置link.distance、manyBody.strength等），可以进一步参考定制不同节点的参数相关示例，其本质都是利用参数的回调函数形式实现"按数据驱动布局"。

总结

d3-force是 G6 中灵活性最高的内置布局之一：五种基础力（链接、多体、中心、碰撞、径向）覆盖了绝大多数图布局诉求，X/Y 轴力又为纵向、横向约束提供了补充手段；配合alpha迭代控制系统与drag-element-force行为，可以轻松构建"自动排布 + 实时交互"的图可视化场景。调参时建议遵循"先锁定link与manyBody决定整体结构，再用collide消除重叠，最后用center/radial/x/y做整体整形"的顺序，能更快得到理想的布局效果。