VR中的3D力导向图

一个用于在虚拟现实中使用力导向迭代布局表示图数据结构的Web组件。使用A-Frame进行VR渲染，使用d3-force-3d作为布局物理引擎。

另请参阅AR版本、WebGL 3D版本和A-Frame组件版本(aframe-forcegraph-component)。

查看React绑定。

示例

快速开始

import ForceGraphVR from '3d-force-graph-vr';

或使用script标签

<script src="//unpkg.com/3d-force-graph-vr"></script>

然后

const myGraph = ForceGraphVR();
myGraph(myDOMElement)
  .graphData(myData);

API参考

数据输入

方法	描述	默认值
<b>graphData</b>([<i>data</i>])	图数据结构的获取器/设置器（语法详情见下文）。	`{ nodes: [], links: [] }`
<b>jsonUrl</b>([<i>url</i>])	直接加载图数据的JSON文件URL，作为直接指定<i>graphData</i>的替代方案。
<b>nodeId</b>([<i>str</i>])	节点对象访问器属性，用于唯一节点ID（在链接对象的源/目标中使用）。	`id`
<b>linkSource</b>([<i>str</i>])	链接对象访问器属性，指向源节点的ID。	`source`
<b>linkTarget</b>([<i>str</i>])	链接对象访问器属性，指向目标节点的ID。	`target`

容器布局

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

节点样式

方法	描述	默认值
<b>nodeRelSize</b>([<i>num</i>])	每单位值的节点球体体积（立方像素）比率的获取器/设置器。	4
<b>nodeVal</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	节点对象访问器函数、属性或数值常量，用于节点数值（影响球体体积）。	`val`
<b>nodeLabel</b>([<i>str</i> 或 <i>fn</i>])	节点对象访问器函数或属性，用于名称（显示在标签中）。	`name`
<b>nodeDesc</b>([<i>str</i> 或 <i>fn</i>])	节点对象访问器函数或属性，用于描述（显示在标签下方）。	`desc`
<b>nodeVisibility</b>([<i>boolean</i>, <i>str</i> 或 <i>fn</i>])	节点对象访问器函数、属性或布尔常量，用于决定是否显示节点。	`true`
<b>nodeColor</b>([<i>str</i> 或 <i>fn</i>])	节点对象访问器函数或属性，用于节点颜色（影响球体颜色）。	`color`
<b>nodeAutoColorBy</b>([<i>str</i> 或 <i>fn</i>])	节点对象访问器函数（`fn(node)`）或属性（如`'type'`），用于自动按组分配颜色。仅影响没有颜色属性的节点。
<b>nodeOpacity</b>([<i>num</i>])	节点球体不透明度的获取器/设置器，范围在[0,1]之间。	0.75
<b>nodeResolution</b>([<i>num</i>])	每个节点几何分辨率的获取器/设置器，表示为将圆周分割成多少个切片段。值越高，球体越平滑。	8
<b>nodeThreeObject</b>([<i>Object3d</i>, <i>str</i> 或 <i>fn</i>])	节点对象访问器函数或属性，用于生成自定义3D对象作为图形节点渲染。应返回ThreeJS Object3d的实例。如果返回<i>假值</i>，将为该节点使用默认3D对象类型。	默认节点对象是一个球体，大小根据`val`确定，样式根据`color`确定。
<b>nodeThreeObjectExtend</b>([<i>bool</i>, <i>str</i> 或 <i>fn</i>])	节点对象访问器函数、属性或布尔值，用于决定在使用自定义`nodeThreeObject`时是替换默认节点（`false`）还是扩展它（`true`）。	`false`

链接样式

方法	描述	默认值
<b>linkLabel</b>([<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数或属性，用于名称（显示在标签中）。	`name`
<b>linkDesc</b>([<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数或属性，用于描述（显示在标签下方）。	`desc`
<b>linkVisibility</b>([<i>布尔值</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数、属性或布尔常量，用于确定是否显示链接线。值为 `false` 时保持链接力而不渲染它。	`true`
<b>linkColor</b>([<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数或属性，用于线条颜色。	`color`
<b>linkAutoColorBy</b>([<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数（`fn(link)`）或属性（如 `'type'`），用于自动按组分配颜色。仅影响没有颜色属性的链接。
<b>linkOpacity</b>([<i>数字</i>])	链接线条不透明度的获取/设置器，取值范围 [0,1]。	0.2
<b>linkWidth</b>([<i>数字</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数、属性或数字常量，用于链接线宽。值为零时将渲染一个 ThreeJS Line，其宽度恒定（`1px`）且不随距离变化。值会四舍五入到最接近的小数以用于索引。	0
<b>linkResolution</b>([<i>数字</i>])	每个链接几何分辨率的获取/设置器，表示将圆柱体分成多少个径向段。较高的值会产生更平滑的圆柱体。仅适用于宽度为正值的链接。	6
<b>linkCurvature</b>([<i>数字</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数、属性或数字常量，用于链接线的曲率半径。曲线表示为 3D 贝塞尔曲线，接受任何数值。值为 `0` 时渲染直线。`1` 表示半径等于线长的一半，使曲线近似半圆。对于自引用链接（`source` 等于 `target`），曲线表示为围绕节点的环，长度与曲率值成正比。正值时线条顺时针弯曲，负值时逆时针弯曲。请注意，渲染曲线仅是视觉效果，不影响底层力的行为。	0
<b>linkCurveRotation</b>([<i>数字</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数、属性或数字常量，用于沿线轴应用于曲线的旋转。对直线没有影响。旋转为 `0` 时，曲线朝向与 `XY` 平面相交的方向。旋转角度（弧度）将使曲线从这个参考方向围绕"起点到终点"轴顺时针旋转。	0
<b>linkMaterial</b>([<i>Material</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数或属性，用于指定自定义材质来样式化图形链接。应返回 ThreeJS Material 的实例。如果返回假值，将为该链接使用默认材质。	默认链接材质是根据 `color` 和 `opacity` 样式化的 MeshLambertMaterial。
<b>linkThreeObject</b>([<i>Object3d</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数或属性，用于生成自定义 3D 对象来渲染图形链接。应返回 ThreeJS Object3d 的实例。如果返回假值，将为该链接使用默认 3D 对象类型。	默认链接对象是线条或圆柱体，大小根据 `width` 确定，样式根据 `material` 确定。
<b>linkThreeObjectExtend</b>([<i>布尔值</i>、<i>字符串</i> 或 <i>函数</i>])	链接对象的访问器函数、属性或布尔值，用于确定在使用自定义 `linkThreeObject` 时是替换默认链接（`false`）还是扩展它（`true`）。	`false`
<b>linkPositionUpdate</b>([<i>fn(linkObject, { start, end }, link)</i>])	获取/设置在每次渲染迭代时用于更新链接位置的自定义函数。该函数接收相应的链接 `ThreeJS Object3d`、链接的起点和终点坐标（每个都是 `{x,y,z}`），以及链接的 `data`。如果函数返回真值，则不会为该链接运行常规位置更新函数。
<b>linkDirectionalArrowLength</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	链接对象访问器函数、属性或数值常量，用于指示链接方向性的箭头头部长度。箭头直接显示在链接线上，指向 `source` > `target` 方向。值为 `0` 时隐藏箭头。	0
<b>linkDirectionalArrowColor</b>([<i>str</i> 或 <i>fn</i>])	链接对象访问器函数或属性，用于设置箭头头部的颜色。	`color`
<b>linkDirectionalArrowRelPos</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	链接对象访问器函数、属性或数值常量，用于设置箭头头部沿链接线的纵向位置，表示为 `0` 到 `1` 之间的比率，其中 `0` 表示紧邻 `source` 节点，`1` 表示紧邻 `target` 节点，`0.5` 表示正中间。	0.5
<b>linkDirectionalArrowResolution</b>([<i>num</i>])	获取/设置箭头头部的几何分辨率，表示为将圆锥底部周长分成多少段。值越高，箭头越平滑。	8
<b>linkDirectionalParticles</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	链接对象访问器函数、属性或数值常量，用于设置在链接线上显示的粒子（小球体）数量。粒子沿线均匀分布，按 `source` > `target` 方向移动，可用于指示链接方向性。	0
<b>linkDirectionalParticleSpeed</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	链接对象访问器函数、属性或数值常量，用于设置方向粒子的速度，表示为每帧移动的链接长度比率。不建议使用高于 `0.5` 的值。	0.01
<b>linkDirectionalParticleWidth</b>([<i>num</i>, <i>str</i> 或 <i>fn</i>])	链接对象访问器函数、属性或数值常量，用于设置方向粒子的宽度。值会四舍五入到最接近的小数，以用于索引目的。	0.5
<b>linkDirectionalParticleColor</b>([<i>str</i> 或 <i>fn</i>])	链接对象访问器函数或属性，用于设置方向粒子的颜色。	`color`
<b>linkDirectionalParticleResolution</b>([<i>num</i>])	获取/设置每个方向粒子的几何分辨率，表示为将周长分成多少段。值越高，粒子越平滑。	4
<b>emitParticle</b>(<i>link</i>)	一种生成粒子的替代机制，此方法在特定链接内发射一个非循环的单个粒子。发射的粒子共享常规粒子属性的样式（速度、宽度、颜色）。应传递一个包含在 `graphData` 中的有效 `link` 对象作为单个参数。

交互

方法	描述	默认值
<b>onNodeHover</b>([<i>fn</i>])	节点悬停事件的回调函数。第一个参数是节点对象（如果指针视线下没有直接节点，则为`null`），第二个参数是前一个节点对象（或`null`）。	-
<b>onLinkHover</b>([<i>fn</i>])	链接悬停事件的回调函数。第一个参数是链接对象（如果指针视线下没有直接链接，则为`null`），第二个参数是前一个链接对象（或`null`）。	-
<b>onNodeClick</b>([<i>fn</i>])	节点点击事件的回调函数。唯一参数是节点对象。	-
<b>onLinkClick</b>([<i>fn</i>])	链接点击事件的回调函数。唯一参数是链接对象。	-

力导向引擎配置

方法	描述	默认值
<b>forceEngine</b>([<i>str</i>])	获取/设置使用的力模拟引擎（d3 或 ngraph）。	`d3`
<b>numDimensions</b>([<i>int</i>])	获取/设置力模拟运行的维度数（1、2 或 3）。	3
<b>dagMode</b>([<i>str</i>])	根据图的方向性应用布局约束。仅适用于 DAG 图结构（无循环）。可选 `td`（自上而下）、`bu`（自下而上）、`lr`（从左到右）、`rl`（从右到左）、`zout`（从近到远）、`zin`（从远到近）、`radialout`（向外辐射）或 `radialin`（向内辐射）。
<b>dagLevelDistance</b>([<i>num</i>])	当启用 `dagMode` 时，指定不同图层深度之间的距离。	根据节点数量自动推导
<b>dagNodeFilter</b>([<i>fn</i>])	节点访问函数，用于指定在 DAG 布局处理过程中要忽略的节点。此访问方法接收一个节点对象，应返回一个 `boolean` 值，表示是否包含该节点。被排除的节点将不受约束，可自由移动到任何方向。	`node => true`
<b>onDagError</b>([<i>fn</i>])	在处理 DAG 布局的数据结构时遇到循环时调用的回调函数。图的循环部分作为节点 ID 数组包含在内，以供参考。默认情况下，遇到循环时会抛出异常。您可以重写此方法以在外部处理这种情况，并允许图继续进行 DAG 处理。如果遇到循环，则无法保证严格的图方向性，结果是尽最大努力建立层次结构。	抛出异常
<b>d3AlphaMin</b>([<i>num</i>])	获取/设置模拟 alpha 最小值参数，仅适用于使用 d3 模拟引擎时。	`0`
<b>d3AlphaDecay</b>([<i>num</i>])	获取/设置模拟强度衰减参数，仅适用于使用 d3 模拟引擎时。	`0.0228`
<b>d3VelocityDecay</b>([<i>num</i>])	获取/设置节点的速度衰减，用于模拟介质阻力，仅适用于使用 d3 模拟引擎时。	`0.4`
<b>d3Force</b>(<i>str</i>, [<i>fn</i>])	获取/设置控制 d3 模拟引擎的内部力。遵循与 `d3-force-3d` 的 simulation.force 相同的接口。默认包含三种力：`'link'`（基于 forceLink）、`'charge'`（基于 forceManyBody）和 `'center'`（基于 forceCenter）。可以重新配置这些力，或向系统添加新的力。此方法仅适用于使用 d3 模拟引擎时。
<b>d3ReheatSimulation</b>()	通过将 `alpha` 值设置为 `1` 来重新激活力模拟引擎。仅适用于使用 d3 模拟引擎时。
<b>ngraphPhysics</b>([<i>object</i>])	根据 ngraph 的配置对象语法指定自定义物理配置。此方法仅适用于使用 ngraph 模拟引擎时。	ngraph 默认值
<b>warmupTicks</b>([<i>int</i>])	获取/设置在开始渲染之前进行预热的布局引擎周期数。	0
<b>cooldownTicks</b>([<i>int</i>])	获取/设置在停止和冻结布局引擎之前渲染的内置帧数。	无穷大
<b>cooldownTime</b>([<i>num</i>])	获取/设置在停止和冻结布局引擎之前渲染的时间（毫秒）。	15000
<b>onEngineTick</b>(<i>fn</i>)	在模拟引擎的每个周期调用的回调函数。	-
<b>onEngineStop</b>(<i>fn</i>)	当模拟引擎停止且布局冻结时调用的回调函数。	-
<b>refresh</b>()	重新绘制所有节点/链接。

工具函数

| <b>getGraphBbox</b>() | 返回图中所有节点的当前边界框，格式为 { x: [<num>, <num>], y: [<num>, <num>], z: [<num>, <num>] }。 ||

输入 JSON 语法

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