3D Force-Directed Graph 使用文档3D Force-Directed Graph 使用文档 3D力

3D Force-Directed Graph 使用文档

3D力导向图是一种在三维空间中可视化网络关系的数据可视化技术。它通过模拟物理系统中的斥力（节点间）和引力（连接间）自动计算节点位置，形成直观的网络结构。

基础使用

安装

# 使用 npm
npm install 3d-force-graph

# 使用 yarn
yarn add 3d-force-graph

基本用法

<div id="3d-graph"></div>

<script type="module">
  import ForceGraph3D from '3d-force-graph';

  // 初始化图表
  const Graph = ForceGraph3D()
 	.graphData(myGraphData)
  	.width(800)
  	.height(600)
  	(document.getElementById('3d-graph'));
</script>

数据结构

{
    "nodes": [
        {
          "id": "id1",
          "name": "name1",
          "val": 1
        },
        {
          "id": "id2",
          "name": "name2",
          "val": 10
        },
        ...
    ],
    "links": [
        {
            "source": "id1",
            "target": "id2"
        },
        ...
    ]
}

节点处理

重写nodeThreeObject方法实现自定义节点渲染，使用ThreeJS原生实现节点绘制

API 文档

初始化 (Initialisation)

方法	描述	默认值
`new ForceGraph3D(<domElement>, { configOptions })`	初始化3D力导向图	-
配置选项
`controlType: str`	摄像机控制类型：`trackball`(轨迹球)/`orbit`(轨道)/`fly`(飞行)	`trackball`
`rendererConfig: object`	ThreeJS WebGLRenderer 配置参数	`{ antialias: true, alpha: true }`
`extraRenderers: array`	额外渲染器实例（如 CSS3DRenderer）	`[]`

数据输入 (Data input)

方法	描述	默认值
`graphData([data])`	图数据结构获取器/设置器（支持增量更新）	`{ nodes: [], links: [] }`
`jsonUrl([url])`	从JSON URL加载图数据	-
`nodeId([str])`	节点唯一ID访问器	`id`
`linkSource([str])`	链接源节点ID访问器	`source`
`linkTarget([str])`	链接目标节点ID访问器	`target`

容器布局 (Container layout)

方法	描述	默认值
`width([px])`	画布宽度获取器/设置器	`<窗口宽度>`
`height([px])`	画布高度获取器/设置器	`<窗口高度>`
`backgroundColor([str])`	背景色获取器/设置器	`#000011`
`showNavInfo([boolean])`	是否显示导航控件信息	`true`

节点样式 (Node styling)

方法	描述	默认值
`nodeRelSize([num])`	节点球体体积比率获取器/设置器	`4`
`nodeVal([num, str or fn])`	节点数值访问器（影响球体大小）	`val`
`nodeLabel([str or fn])`	节点标签访问器（支持文本/HTML）	`name`
`nodeVisibility([boolean, str or fn])`	节点显示开关访问器	`true`
`nodeColor([str or fn])`	节点颜色访问器	`color`
`nodeAutoColorBy([str or fn])`	按属性自动分组颜色访问器	-
`nodeOpacity([num])`	节点透明度获取器/设置器 [0,1]	`0.75`
`nodeResolution([num])`	节点几何分辨率（分段数）	`8`
`nodeThreeObject([Object3d, str or fn])`	自定义节点3D对象访问器	默认球体
`nodeThreeObjectExtend([bool, str or fn])`	自定义节点扩展模式（替换/扩展）	`false`
`nodePositionUpdate([fn])`	节点位置更新回调函数	-

链接样式 (Link styling)

方法	描述	默认值
`linkLabel([str or fn])`	链接标签访问器	`name`
`linkVisibility([boolean, str or fn])`	链接显示开关访问器	`true`
`linkColor([str or fn])`	链接颜色访问器	`color`
`linkAutoColorBy([str or fn])`	按属性自动分组颜色访问器	-
`linkOpacity([num])`	链接透明度获取器/设置器 [0,1]	`0.2`
`linkWidth([num, str or fn])`	链接宽度访问器	`0`
`linkResolution([num])`	链接几何分辨率（分段数）	`6`
`linkCurvature([num, str or fn])`	链接曲率访问器（0=直线）	`0`
`linkCurveRotation([num, str or fn])`	曲线旋转角度访问器（弧度）	`0`
`linkMaterial([Material, str or fn])`	链接材质访问器	默认材质
`linkThreeObject([Object3d, str or fn])`	自定义链接3D对象访问器	默认线/圆柱体
`linkThreeObjectExtend([bool, str or fn])`	自定义链接扩展模式	`false`
`linkPositionUpdate([fn])`	链接位置更新回调	-
`linkDirectionalArrowLength([num, str or fn])`	方向箭头长度访问器	`0`
`linkDirectionalArrowColor([str or fn])`	箭头颜色访问器	`color`
`linkDirectionalArrowRelPos([num, str or fn])`	箭头相对位置访问器 [0,1]	`0.5`
`linkDirectionalArrowResolution([num])`	箭头几何分辨率	`8`
`linkDirectionalParticles([num, str or fn])`	方向粒子数量访问器	`0`
`linkDirectionalParticleSpeed([num, str or fn])`	粒子速度访问器	`0.01`
`linkDirectionalParticleWidth([num, str or fn])`	粒子宽度访问器	`0.5`
`linkDirectionalParticleColor([str or fn])`	粒子颜色访问器	`color`
`linkDirectionalParticleResolution([num])`	粒子几何分辨率	`4`
`emitParticle(link)`	在指定链接发射粒子	-

渲染控制 (Render control)

方法	描述	默认值
`pauseAnimation()`	暂停渲染循环（冻结视图）	-
`resumeAnimation()`	恢复渲染循环	-
`cameraPosition([{x,y,z}], [lookAt], [ms])`	摄像机位置/朝向设置（含过渡动画）	自动居中
`zoomToFit([ms], [px], [nodeFilterFn])`	缩放到适应画布	`(0, 10, node => true)`
`postProcessingComposer()`	访问后期处理合成器	-
`lights([array])`	光源设置	环境光+方向光
`scene()`	访问ThreeJS场景对象	-
`camera()`	访问ThreeJS摄像机	-
`renderer()`	访问WebGL渲染器	-
`controls()`	访问控制对象	-
`refresh()`	重绘所有节点/链接	-

力学引擎配置 (Force engine configuration)

方法	描述	默认值
`forceEngine([str])`	力学引擎选择：`d3` 或 `ngraph`	`d3`
`numDimensions([int])`	模拟维度数（1/2/3）	`3`
`dagMode([str])`	DAG布局模式（8种方向）	-
`dagLevelDistance([num])`	DAG层级间距	自动计算
`dagNodeFilter([fn])`	DAG节点过滤器	`node => true`
`onDagError([fn])`	DAG循环错误回调	抛出异常
`d3AlphaMin([num])`	d3引擎alpha最小值	`0`
`d3AlphaDecay([num])`	d3引擎衰减率	`0.0228`
`d3VelocityDecay([num])`	d3速度衰减率	`0.4`
`d3Force(str, [fn])`	d3力配置（link/charge/center）	-
`d3ReheatSimulation()`	重启d3引擎（alpha=1）	-
`ngraphPhysics([object])`	ngraph物理配置	默认配置
`warmupTicks([int])`	布局预热迭代次数	`0`
`cooldownTicks([int])`	自动停止前渲染帧数	`Infinity`
`cooldownTime([num])`	自动停止前渲染时间(ms)	`15000`
`onEngineTick(fn)`	引擎每步迭代回调	-
`onEngineStop(fn)`	引擎停止回调	-

交互 (Interaction)

方法	描述	默认值
`onNodeClick(fn)`	节点左键点击回调	-
`onNodeRightClick(fn)`	节点右键点击回调	-
`onNodeHover(fn)`	节点悬停回调	-
`onNodeDrag(fn)`	节点拖拽中回调	-
`onNodeDragEnd(fn)`	节点拖拽结束回调	-
`onLinkClick(fn)`	链接左键点击回调	-
`onLinkRightClick(fn)`	链接右键点击回调	-
`onLinkHover(fn)`	链接悬停回调	-
`onBackgroundClick(fn)`	背景点击回调	-
`onBackgroundRightClick(fn)`	背景右键回调	-
`linkHoverPrecision([int])`	链接悬停检测精度	`1`
`enablePointerInteraction([boolean])`	启用鼠标跟踪交互	`true`
`enableNodeDrag([boolean])`	启用节点拖拽（仅d3引擎）	`true`
`enableNavigationControls([boolean])`	启用摄像机导航控制	`true`

工具方法 (Utility)

方法	描述
`getGraphBbox([nodeFilterFn])`	获取节点边界框 `{x,y,z}`
`graph2ScreenCoords(x, y, z)`	图坐标 → 视口坐标转换
`screen2GraphCoords(x, y, distance)`	视口坐标 → 图坐标转换