力与布局

阅读时间约 10 分钟

`graph.forceMap`

object

内置 map 对象用于记录所有作用力（包含内置力与自定义力），与 simulation 中的力保持同步。

作用力集合 forceMap 内置的作用力:

graph.forceMap = {
    forceCenter: null, // 向心力
    forceCollide: null, // 碰撞力
    forceLink: null, // 线牵引力
    forceManyBody: null, // 电荷力
    forceX: null, // 定位力x
    forceY: null, // 定位力y
    forceRadial: null, // 环形力
    forceRect: null, // 矩形力
    forceCluster: null, // 聚簇力
}

作用力常量 Forces:

export const Forces = {
    forceCenter: d3.forceCenter, // 向心力
    forceCollide: d3.forceCollide, // 碰撞力
    forceLink: d3.forceLink, // 线牵引力
    forceManyBody: d3.forceManyBody, // 电荷力
    forceX: d3.forceX, // 定位力x
    forceY: d3.forceY, // 定位力y
    forceRadial: d3.forceRadial, // 环形力
    forceRect, // 矩形力
    forceCluster, // 聚簇力
}

// 在代码中使用
import ForceGraphVis, { Forces } from '@snfe/force-graph-vis'
// 初始化图
const graph = new ForceGraphVis({ /*...*/ })
// 设置作用力
graph.setForceOption({
    forceCenter: Forces.forceCenter(0, 0),// 设置向心力
    forceCustom: xxx // 设置用户自定义力
})

`graph.changeLayout(type = 'force', options={})`

Function

切换布局，目前支持 6 种内置的布局类型，每种布局类型都对应一组作用力，切换布局时同步到作用力集合 forceMap 中

参数

type : force | ring | layer | rect | cluster | radial optional

布局类型，默认为 force 力导向布局
options : object optional

布局配置项，不同布局类型的配置项如下：
- force 力导向布局（动态） 该布局无配置项
- radial 放射布局（动态） 该布局无配置项
- rect 网格布局（动态）
  - columnN : number required 布局列数，必填
  - rowN : number required 布局行数，必填
  - width : number optional 布局宽度，默认为画布的宽度
  - height : number optional 布局高度，默认为画布的高度
  - x : obeject optional 布局水平偏移，默认为 0
  - y : number optional 布局垂直偏移，默认为 0
  - xCenter : obeject optional 网格水平中心，默认为 0.5
  - yCenter : number optional 网格垂直中心，默认为 0.5
- cluster 聚簇布局（动态）
  - clusterCenter : string required
    
    在节点数据配置中增加 clusterCenter 配置项，指向聚簇中心节点的 ID
```
{
    "nodes": [{
       "id": "a", // 节点id
       "name": "节点A", // 节点文字
    },{
       "id": "b", // 节点id
       "name": "节点B", // 节点文字
       "clusterCenter": 'a', // 聚簇中心指向节点a
    }]
} 
```
- ring 环形层级布局（静态）
  - root : string required 根节点 ID，必填
  - width : number optional 布局宽度，默认为画布的宽度
  - height : number optional 布局高度，默认为画布的高度
  - radius : number optional 环形层级半径，默认为画布高度或宽度一半的最小值
  - top : number optional 布局上边距，默认为 30
  - bottom : number optional 布局下边距，默认为 30
  - left : number optional 布局左边距，默认为 30
  - right : number optional 布局右边距，默认为 30
  - expandFirst : 'next' | 'prev' optional 优先展开根节点的下层级 / 上层级
  - nextFarFirst = false : boolean optional 节点优先在远的一侧
- layer 层级布局（静态）
  - root : string | Array<string> required 根节点 id，通常情况下是 string 类型，支持多个根节点以数组形式传入
  - expandFirst = 'next' : 'next' | 'prev' optional 优先展开根节点的下层级 / 上层级，默认下层级
  - width : number optional 布局宽度，默认为画布的宽度
  - height : number optional 布局高度，默认为画布的高度
  - levelGap : number optional 布局层级间距，350
  - nodeGap : number optional 布局节点间距，默认为 2
  - padding : obeject optional 布局边距，默认为 { top: 30, bottom: 30, left: 30, right: 30 }
  - maxLevel = Infinity : number optional 最大层数，默认无限制
  - initDuration : number optional 初始动画持续时间，默认为 1500
- 所有布局类型共有配置项
  - forceUseType : merge | cover optional
    
    设置作用力时的行为类型，详细参数参考下方 graph.setForceOption 方法中的 forceUseType 参数plainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplainplain
  - force : object optional
    
    作用力参数，修改布局时默认使用的作用力，用于调整内置布局的行为，详细参数参考下方 graph.setForceOption 方法中的 forceOption 参数plainplainplainplainplainplainplainplainplainplainplainplainplainplainplain

`graph.setForceOption(forceOption = {}, forceUseType = 'merge')`

设置作用力，可以接收对象类型/函数类型的参数，具有合并/覆盖当前作用力集合的两种行为

参数

forceUseType : merge | cover optional

设置作用力时的行为类型，默认为合并模式，merge: 与当前作用力集合 forceMap 合并，cover: 覆盖当前作用力集合 forceMap

forceOption : object | Function optional

作用力参数

当传入object类型时，如果要修改内置作用力，应与forceMap中的 key 保持一致，支持添加用户自定义力

forceOption = {
    forceCenter: null, // 向心力
    forceCollide: null, // 碰撞力
    forceLink: null, // 线牵引力
    forceManyBody: null, // 电荷力
    forceX: null, // 定位力x
    forceY: null, // 定位力y
    forceRadial: null, // 环形力
    forceRect: null, // 矩形力
    forceCluster: null, // 聚簇力
    xxx: null // 用户自定义力
}

当传入function类型时，forceOption将作为回调函数被执行

forceOption = (forceMap, graph) => {
   return {
       forceCenter: null, // 向心力
       forceCollide: null, // 碰撞力
       forceLink: null, // 线牵引力
       forceManyBody: null, // 电荷力
       forceX: null, // 定位力x
       forceY: null, // 定位力y
       forceRadial: null, // 环形力
       forceRect: null, // 矩形力
       forceCluster: null, // 聚簇力
       xxx: null // 用户自定义力
   }
}

回调函数参数

forceMap : object

当 forceUseType = 'merge' 时，该参数为图谱实例的作用力集合，当 forceUseType = 'cover' 时，该参数为空对象
graph 当前图谱实例

回调函数返回值

newForceMap : object required

当 forceUseType = 'cover' 时，回调函数必须返回一个对象，作为新的作用力集合

`graph.updateForce(key, fn)`

通过 key 修改单个力，只允许修改作用力集合 forceMap 中已经存在的力

参数

key : string required

作用力名称
fn : function required

传入回调函数来修改作用力

回调函数参数
- force : function
  
  根据 key 获取到的作用力函数
回调函数返回值
- newForce : function required
  
  返回修改之后的作用力函数

`graph.setForce(key, value)`

通过 key 设置单个力，覆盖作用力集合中对应的力，允许设置用户自定义力

参数

key : string required

作用力名称
value : function required

作用力函数

`graph.clearForces()`

清除所有力，适用于无力学模拟下的静态布局，自定义布局的场景

`graph.updateForces()`

内部调用方法，基于 forceMap 更新 simulation 中的所有作用力，正常情况下无需调用，除非用户手动修改作用力集合（强烈不建议）