G6 布局通用配置项完全指南：LayoutOptions 核心字段与运行机制

数据可视化前端图表库【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址https://gitcode.com/gh_mirrors/g6/G6点击查看免费下载本文围绕 AntV G6 布局系统的通用配置项展开系统讲解Graph的layout配置中所有通用字段type、preLayout、nodeFilter、iterations、animation等的语义、默认值与适用场景并结合仓库源码剖析 G6 布局控制器LayoutController的前/后布局管线与过滤逻辑。读完本文你将能够独立配置任何内置或自定义布局的通用参数理解布局动画与迭代布局的执行差异并掌握多布局流水线pipeline的用法。布局配置的入口Graph 的layout选项在 G6 中布局通过Graph构造时的layout字段声明。layout的完整类型定义是LayoutOptions SingleLayoutOptions | SingleLayoutOptions[]见 spec/layout.ts即既可以是一个单布局配置对象也可以是多个布局配置组成的数组后者会按顺序依次执行形成布局流水线pipeline。const graph new Graph({ container: container, data, layout: { type: antv-dagre, // 布局类型通用配置中最核心的字段 // ...其他通用配置与布局私有配置 }, });除了初始化配置G6 还在运行时提供了四个与布局相关的 API实现于 runtime/graph.tssetLayout(layout | (prev) next)动态修改布局配置传入函数时可根据旧配置计算新配置getLayout()读取当前布局配置layout(layoutOptions?)手动触发一次布局计算等价于执行布局管线的postLayoutgraph.tsstopLayout()停止迭代型布局如force的迭代动画常用于迭代时间过长时在点击画布/节点事件里手动终止graph.ts。通用配置项全解下表即本文的核心也是所有布局内置与自定义共用的配置字段定义于 layouts/types.ts 的BaseLayoutOptions属性描述类型默认值必选type布局类型内置布局或自定义布局的名称Type-✓isLayoutInvisibleNodes不可见节点是否参与布局当 preLayout 为 true 时生效booleanfalsenodeFilter参与该布局的节点(node: NodeData) boolean() truecomboFilter参与该布局的 combo 元素(combo: ComboData) boolean() truepreLayout使用前布局在初始化元素前计算布局booleanfalseenableWorker是否在 WebWorker 中运行布局boolean-iterations迭代布局的迭代次数number-animation是否启用布局动画booleanfalsewidth布局区域宽度默认使用当前容器宽度number-height布局区域高度默认使用当前容器高度number-center布局中心点[number, number] \| [number, number, number]-node节点字段映射用于把业务字段映射为布局字段(datum) ({ id?, x?, y?, z?, parentId?, isCombo? })-edge边字段映射用于把业务字段映射为布局字段(datum) ({ id?, source?, target? })-补充说明width/height/center是antv/layout统一支持的通用布局字段node/edge用于适配非标准id/source/target业务数据iterations是 G6 运行时用于驱动迭代布局的步数不等同于某些布局内部自己的算法参数。type布局类型的名称type必选指定使用哪个内置布局或自定义布局。布局实例通过扩展注册表registry按名称获取getExtension(layout, type)见 runtime/layout.ts。若名称未注册控制台会打印警告The layout of ${type} is not registered.且跳过该布局。const graph new Graph({ // 其他配置... layout: { type: antv-dagre, }, });内置type的可选值及对应文档如下type说明对应文档antv-dagre基于 dagre 定制的布局AntvDagreLayout.zh.mdcircular环形布局CircularLayout.zh.mdcombo-combined适用于存在组合的布局ComboCombinedLayout.zh.mdconcentric同心圆布局ConcentricLayout.zh.mdd3-force基于 D3 的力导向布局D3ForceLayout.zh.mdd3-force-3d3D 力导向布局D3Force3DLayout.zh.mddagredagre 布局DagreLayout.zh.mdfishbone鱼骨布局Fishbone.zh.mdforce力导向布局ForceLayout.zh.mdforce-atlas2ForceAtlas2 布局ForceAtlas2Layout.zh.mdfruchtermanFruchterman 布局FruchtermanLayout.zh.mdgrid网格布局GridLayout.zh.mdmds高维数据降维算法布局MdsLayout.zh.mdradial径向布局RadialLayout.zh.mdrandom随机布局RandomLayout.zh.mdsnake蛇形布局Snake.zh.mdcompact-box紧凑树布局CompactBoxLayout.zh.mddendrogram树状布局DendrogramLayout.zh.mdmindmap思维导图布局MindmapLayout.zh.mdindented缩进树布局IndentedLayout.zh.md这些内置类型的名称声明可以在 layouts/types.ts 的BuiltInLayoutOptions联合类型中逐一定义例如force布局的类型为force | gforcefruchterman为fruchterman | fruchterman-gpud3-force-3d的注册名称为d3-force3d配置时请以对应文档与类型声明为准。除内置布局外type也可以填写通过register(layout, ...)注册的自定义布局名称参见 custom-layout.zh.md。preLayout与isLayoutInvisibleNodes控制布局执行时机与节点范围preLayout前布局表示在元素初始化之前就计算布局适合需要提前确定节点位置的场景如某些布局依赖画布尺寸。从源码看G6 渲染流程中会先判断是否为前布局再决定执行顺序runtime/graph.tsif (!this.options.layout) { // 无布局直接绘制 } else if (!this.rendered isPreLayout(this.options.layout)) { // 前布局先计算位置再初始化元素 await this.context.layout!.preLayout(drawData); ... } else { // 后布局先绘制再执行布局 await Promise.all([animation?.finished, this.context.layout!.postLayout()]); }判断逻辑在 utils/layout.tsisPreLayout要求layout不是数组且配置了preLayout: true。也就是说前布局不适用于流水线布局多布局数组这一点在BaseLayoutOptions.preLayout的源码注释中也有明确说明layouts/types.ts。isLayoutInvisibleNodes只在preLayout为 true 时生效layouts/types.ts。在前布局模式下默认情况下以下节点会被排除在布局之外style.visibility hidden的节点祖先树结构TREE_KEY或 combo 结构COMBO_KEY处于折叠状态的节点对应逻辑见 runtime/layout.ts 的filterFn。当isLayoutInvisibleNodes: true时这些不可见节点也会参与布局计算。nodeFilter与comboFilter按业务条件筛选参与布局的元素两个过滤函数分别控制节点与 combo 是否参与该布局默认均为() true。布局控制器在getLayoutData中会基于这两个函数筛选出待布局数据并且只保留两端节点都在布局集合内的边runtime/layout.ts。需要注意非前布局后布局模式下节点的元素必须已经存在且未被销毁才会参与布局runtime/layout.ts这保证了布局不会作用于尚未渲染的元素。典型用法是只对某一类节点布局const graph new Graph({ layout: { type: force, nodeFilter: (node) node.data.category ! fixed, // 固定节点不参与力导向计算 comboFilter: (combo) combo.style.visible ! false, }, });enableWorker与iterations迭代布局的执行控制enableWorker声明是否在 WebWorker 中运行布局类型声明见WebWorkerLayoutOptionslayouts/types.ts其实际可用性取决于所选用布局对 worker 的支持情况配置前建议查阅具体布局文档。iterations是 G6 运行时驱动迭代布局iterative layout如force、fruchterman的总迭代步数它不等同于某些布局内部自带的算法参数。在graphLayout中可以看到它的实际消费方式runtime/layout.tsconst { animation, iterations 300 } options; // 默认 300 步 if (isLayoutWithIterations(layout)) { if (animation) { // 有动画基于 tick 逐帧更新位置 return await layout.execute(data, { animate: true, maxIteration: iterations, onTick: ... }); } // 无动画直接执行到终态 layout.execute(data); layout.stop(); return layout.tick(iterations); }即未显式配置时迭代步数默认为 300开启animation后每次迭代都会通过onTick回调驱动元素位置更新形成逐步趋稳的动画效果。animation是否启用布局动画默认false。开启后对迭代布局isLayoutWithIterations为 true 的布局会在两次迭代之间进行动画过渡对非迭代布局会在终态位置计算完成后做一次从当前位置到目标位置的补间动画runtime/layout.ts。另外G6 会把全局动画配置注入布局选项LayoutController.presetOptions会在全局动画开启时默认置animation: trueruntime/layout.ts因此布局动画的最终生效是全局动画配置 布局配置共同作用的结果。width/height/center布局区域的几何约束这三个字段由antv/layout统一支持。不配置时G6 在initGraphLayout中会自动取画布尺寸并计算中心点runtime/layout.tsconst [width, height] viewport!.getCanvasSize(); const center [width / 2, height / 2];对d3-force/d3-force-3d这类三维坐标布局中心点会被特殊处理为{ x, y, z }对象形式runtime/layout.ts。此外布局所需的nodeSize也会被自动推导优先取配置值否则从元素的实际尺寸element.attributes.size或节点样式计算得出runtime/layout.ts这也是布局区域计算的重要输入。node/edge业务字段到布局字段的映射当业务数据的节点、边没有使用标准的id/source/target字段或需要自定义parentId、isCombo等派生字段时可以通过这两个函数将业务数据映射为布局所需的结构。源码中的默认实现展示了标准的映射形态utils/layout.tsconst defaultNode (datum) ({ id, ...(style?.x ! null ? { x: style.x } : {}), ...(style?.y ! null ? { y: style.y } : {}), ...(style?.z ! null ? { z: style.z } : {}), parentId, // 取自 datum.combo ...(isCombo ? { isCombo: true } : {}), }); const defaultEdge (datum) ({ id, source: datum.source, target: datum.target });自定义映射示例const graph new Graph({ data: { nodes: [{ id: n1, data: { bizId: a, pos: [10, 20] } }] }, layout: { type: grid, node: (datum) ({ id: datum.data.bizId, x: datum.data.pos[0], y: datum.data.pos[1] }), edge: (datum) ({ id: datum.id, source: datum.source, target: datum.target }), }, });布局执行管线的底层机制所有通用配置最终都会汇入LayoutControllerruntime/layout.ts它负责前布局、后布局、模拟布局的调度。理解这条管线有助于判断各配置项何时生效数据获取getLayoutData按nodeFilter/comboFilter/preLayout/isLayoutInvisibleNodes筛选节点与 combo并同步过滤掉不在集合内的边布局分流stepLayout依据isTreeLayoutcompact-box、mindmap、dendrogram、indented四类见 utils/layout.ts分流到树布局管线或图布局管线实例创建initGraphLayout从扩展注册表取出布局类通过适配器layoutAdapter/legacyLayoutAdapterutils/layout.ts将antv/layout的布局统一包装为继承自 BaseLayout 的标准实例并合并width/height/center/nodeSize等默认几何配置执行与回写迭代布局按iterations步进可配合animation的 tick 动画非迭代布局一次性算出终态结果通过model.updateData与element.draw回写元素位置runtime/layout.ts后处理布局结束后触发BEFORE_LAYOUT/AFTER_LAYOUT等生命周期事件并调用各 transform 的afterLayout钩子。除antv/layout提供的布局外G6 仓库内还内置了两个自研布局fishbone与snake导出于 layouts/index.ts它们直接继承BaseLayout并实现了各自的算法可作为理解自定义布局需要实现什么的参考范例fishbone.ts、snake.ts。实践建议与注意事项先 type 后参数任何布局配置都必须先确定type通用配置是所有布局的公共底座私有参数请在对应布局文档中查阅流水线场景慎用 preLayoutpreLayout不支持数组形式的流水线布局需要多布局串联时请使用后布局默认行为区分 iterations 与算法内部参数iterations只驱动 G6 运行时的迭代步进若要调整布局算法自身的收敛系数应使用对应布局的私有字段不可见节点的处理默认前布局会跳过隐藏/折叠节点如需让它们参与计算显式设置isLayoutInvisibleNodes: true字段映射保持简单node/edge映射返回的字段只需包含布局实际读取的部分未提供的字段如id?会退回默认逻辑。更完整的布局总览与自定义布局教程可继续阅读 overview.zh.md 与 custom-layout.zh.md。赞分享数据可视化前端图表库【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址https://gitcode.com/gh_mirrors/g6/G6点击查看免费下载相关推荐G6 布局通用配置完全指南BaseLayout 公共参数与内置布局体系解析G6 布局通用配置完全指南BaseLayout 公共参数与内置布局体系解析 本文围绕 G6 antv/g6 中所有内置布局共同支持的通用配置项展开系统数据可视化前端图表库G6 布局 API 完全指南setLayout / getLayout / layout / stopLayout 与布局配置实战G6 布局 API 完全指南setLayout / getLayout / layout / stopLayout 与布局配置实战 G6 antv/g6数据可视化前端图表库G6 随机布局Random Layout完全指南用法、配置与源码级原理解析G6 随机布局Random Layout完全指南用法、配置与源码级原理解析 导读 随机布局Random Layout是 G6 内置布局中最轻量的一种数据可视化前端图表库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考