G6 图配置项 GraphOptions 完全指南getOptions 与 setOptions 动态配置实战【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址: https://gitcode.com/gh_mirrors/g6/G6G6antv/g6是一款基于 JavaScript 的图可视化框架其图实例的每一项外观与行为都由 配置项GraphOptions驱动。本文以 G6 官方 API 文档 option.zh.md 为骨架系统讲解配置项的全貌、graph.getOptions()与graph.setOptions()两个核心 API 的用法与底层实现并结合作者仓库源码与测试用例深入解析配置的动态更新机制。读完本文你将掌握如何在图实例创建时一次性传入完整配置、如何在运行时按需读取与局部更新主题、布局、节点边样式与交互行为并理解哪些配置项必须重建实例才能生效。图配置项概述一份配置掌控图的全部G6 图实例的配置项控制着图的各个方面包括画布设置、视口属性、数据、布局、样式、交互行为、插件等。通过合理配置这些选项可以灵活定制图的外观和行为。从源码类型定义看GraphOptions是一个组合型接口它继承了画布配置项与视口配置项并补充了数据、布局、元素、主题与扩展相关的字段见 packages/g6/src/spec/graph.tsexport interface GraphOptions extends CanvasOptions, ViewportOptions { animation?: boolean | AnimationEffectTiming; // 全局动画开关/基础动画配置 data?: GraphData; // 图数据节点/边/组合 layout?: LayoutOptions; // 布局配置对象或数组 node?: NodeOptions; // 节点全局配置 edge?: EdgeOptions; // 边全局配置 combo?: ComboOptions; // 组合全局配置 theme?: ThemeOptions; // 主题light / dark / 自定义 / false behaviors?: BehaviorOptions; // 交互行为 plugins?: PluginOptions; // 插件 transforms?: TransformOptions; // 数据转换器 }其中CanvasOptions见 packages/g6/src/spec/canvas.ts包含container、width、height、devicePixelRatio、background、cursor、renderer、autoResize、canvas等画布相关字段ViewportOptions见 packages/g6/src/spec/viewport.ts包含x、y、autoFit、padding、rotation、zoom、zoomRange等视口字段。配置项可以在图实例创建时指定作为new Graph(options)的入参也可以通过 API 在运行时动态修改。某些基础配置如devicePixelRatio、container修改后需要销毁并重新创建图实例才能生效这一点在setOptions的官方说明中已被明确标注后文将详述原因。Graph.getOptions()读取当前图表的完整配置方法签名getOptions(): GraphOptions;返回值类型:GraphOptions描述: 当前图表的完整配置项即图实例内部维护的this.options对象。从实现来看见 packages/g6/src/runtime/graph.tsgetOptions直接返回实例上持有的options字段public getOptions(): GraphOptions { return this.options; }这个options字段在构造函数中被初始化为Object.assign({}, Graph.defaultOptions, options)即「框架默认配置」与「用户传入配置」的合并结果。框架的默认配置定义如下见 packages/g6/src/runtime/graph.tsstatic defaultOptions: GraphOptions { autoResize: false, // 默认不随窗口自动调整画布 theme: light, // 默认浅色主题 rotation: 0, // 默认不旋转 zoom: 1, // 默认 100% 缩放 zoomRange: [0.01, 10], // 默认缩放范围 };因此即使你没有显式配置这些字段getOptions()返回的对象中也已经包含上述默认值读取结果总是「最终生效配置」而非「你传入的原始配置」。示例// 获取当前图表的配置项 const options graph.getOptions(); console.log(当前图表配置:, options); // 获取特定配置 console.log(当前画布宽度:, options.width); console.log(当前布局配置:, options.layout);Graph.setOptions()运行时动态更新配置方法签名setOptions(options: GraphOptions): void;参数参数描述类型默认值必选options新的配置项GraphOptions-✓注意参数为部分配置时也会正常工作setOptions采用「按字段合并」策略你只需传入想更新的字段未传入的配置保持不变。⚠️ 关键注意事项要更新devicePixelRatio、container等基础属性需要销毁当前图实例后重新创建。其他大部分配置可以动态更新。为什么会有这个限制从实现角度可以解释container决定画布挂载在哪个 DOM 节点上devicePixelRatio决定画布渲染的物理像素密度这两个参数在画布Canvas初始化时被固化到底层画布实例中见 packages/g6/src/runtime/canvas.ts运行中替换并不会重建底层画布。而enableMultiLayer是否启用多图层同样被标注为「非动态参数仅在初始化时生效」见 packages/g6/src/runtime/canvas.ts。示例 1基本用法// 更新图表配置 graph.setOptions({ width: 1000, // 更新宽度 height: 800, // 更新高度 autoFit: view, // 开启自适应 animation: true, // 启用动画 });示例 2更新主题// 更新图表主题配置 graph.setOptions({ theme: { type: dark, // 切换到暗色主题 // 自定义主题配置 node: { palette: [#1AAF8B, #F8E71C, #8B572A, #7ED321], }, edge: { palette: [#F5A623, #F8E71C, #8B572A, #7ED321], }, }, });主题字段既可以直接传内置主题名字符串light/dark也可以传对象形式进行主题定制还可以设为false表示不使用任何主题。内置的明暗两套主题实现见 packages/g6/src/themes/light.ts 与 packages/g6/src/themes/dark.ts。示例 3更新布局配置// 更新布局配置 graph.setOptions({ layout: { type: force, // 切换到力导向布局 preventOverlap: true, // 防止节点重叠 nodeStrength: -50, // 节点之间的斥力 edgeStrength: 0.7, // 边的弹性系数 }, });示例 4更新节点和边的默认配置// 更新节点和边的默认样式配置 graph.setOptions({ node: { style: { fill: #91d5ff, stroke: #40a9ff, lineWidth: 1, radius: 10, }, }, edge: { style: { stroke: #91d5ff, lineWidth: 2, endArrow: true, }, }, });更新后立即生效的子配置setOptions内部会针对不同字段调用对应的 setter逐一将变更下发到对应控制器见 packages/g6/src/runtime/graph.ts传入字段内部调用效果behaviorssetBehaviors()全量替换交互配置并更新行为控制器datasetData()全量设置数据并触发数据差异计算nodesetNode()更新节点样式映射并刷新模型数据edgesetEdge()更新边样式映射并刷新模型数据combosetCombo()更新组合样式映射并刷新模型数据layoutsetLayout()更新布局配置themesetTheme()更新主题配置pluginssetPlugins()全量替换插件配置并更新插件控制器transformssetTransforms()全量替换数据转换器配置并更新转换控制器仓库配套的单元测试验证了这一行为例如 packages/g6/tests/unit/runtime/graph/graph.spec.ts 中的用例it(getOptions/setOptions, () { graph.setOptions({ zoomRange: [-10, 10] }); expect(graph.getOptions().zoomRange).toEqual([-10, 10]); });同一个测试文件中还有针对setNode/setEdge/setCombo的用例分别验证节点、边、组合状态样式更新后可通过getOptions()读取到新值见 graph.spec.ts可用于回归验证配置的读写闭环。setOptions 的底层原理合并、推断与分发setOptions之所以能做到「只更新传进来的字段」是因为其底层_setOptions采用了Object.assign合并策略并且在合并之前会先执行一层配置推断infer。相关代码位于 packages/g6/src/runtime/options.tsexport function inferOptions(options: GraphOptions): GraphOptions { const flow [inferLayoutOptions]; return flow.reduce((acc, infer) infer(acc), options); }当前实现中只有一个推断器inferLayoutOptions它负责为特定布局自动补充preLayout标记当布局类型为antv-dagre、combo-combined、compact-box、circular、concentric、dagre、fishbone、grid、indented、mds、radial、random、snake、dendrogram、mindmap等时会默认开启preLayout: true。从源码注释可以看出dendrogram与mindmap两类布局的标签位置尚待适配需要手动将其preLayout设为false见 packages/g6/src/runtime/options.ts。这也是为什么你会看到一些布局配置中显式出现preLayout字段——它并非文档强调的参数而是框架为兼容标签位置自动注入的推断结果。另外值得注意setOptions并不会真正「重建」运行时。与销毁重建destroy()后重新new Graph相比setOptions走的是一条轻量路径——合并配置后把变更分发给各控制器因此大部分场景下用它做运行时主题切换、布局切换、样式热更新是最合适的方案。配置项全参考从画布到视口的逐项详解以下内容整理自 G6 官方手册 packages/site/docs/manual/graph/option.zh.md与上文 API 文档互为补充可作为日常配置的速查表。画布相关配置CanvasOptionscontainerstring | HTMLElement | Canvas画布容器可以是以下三种赋值之一DOM 元素的 ID 字符串如containerHTML 元素对象如document.getElementById(container)Canvas 实例如new Canvas(options)其中options为 CanvasConfig 类型width / heightnumber画布宽度/高度。如果未设置则会自动获取容器宽度/高度见 packages/g6/src/spec/canvas.ts。devicePixelRationumber设备像素比用于高清屏默认为window.devicePixelRatio。⚠️ 属于初始化参数修改后需重建实例。backgroundstring画布背景色。该颜色同时作为导出图片时的背景色Canvas.toDataURL会使用this.extends.config.background见 packages/g6/src/runtime/canvas.ts。可以使用任何有效的 CSS 颜色值如十六进制、RGB、RGBA 等。cursorstring指针样式控制鼠标悬停在画布上时的光标形状。支持auto、default、pointer、move、grab、grabbing、crosshair、zoom-in、zoom-out、n-resize、e-resize等所有合法 CSS cursor 值与 MDN cursor 保持一致。renderer(layer: background | main | label | transient) IRenderer手动指定渲染器。G6 采用分层渲染分为background、main、label、transient四层可通过该配置分别设置每层的渲染器见 packages/g6/src/runtime/canvas.ts 中createRenderers的实现。示例使用 SVG 渲染器import { Renderer as SVGRenderer } from antv/g-svg; import { Graph } from antv/g6; const graph new Graph({ renderer: () new SVGRenderer(), });canvasCanvasConfigCanvasConfigGraphOptions 下的相关配置项如container、width、height、devicePixelRatio、background、cursor为快捷配置项会被转换为 canvas 配置项。canvas字段用于直接传入更底层的画布配置属性描述类型默认值必填container画布容器string | HTMLElement-devicePixelRatio设备像素比number-width画布宽度number-height画布高度number-cursor指针样式与 GraphOptions.cursor 配置相同string-background画布背景色string-renderer渲染器与 GraphOptions.renderer 配置相同(layer) IRenderer-enableMultiLayer是否启用多图层。非动态参数仅在初始化时生效boolean-autoResizeboolean默认值:false是否自动调整画布大小。基于window.onresize事件实现当浏览器窗口大小变化时画布将自动调整大小以适应容器构造函数中通过globalThis.addEventListener?.(resize, this.onResize)挂载监听见 packages/g6/src/runtime/graph.ts。视口相关配置ViewportOptionsx / ynumber视口 x / y 坐标设置视口的初始水平/垂直位置。视口控制器在构造时会读取x、y未设置时使用 padding 偏移量进行初始定位见 packages/g6/src/runtime/viewport.ts。zoomnumber默认值:1设置视口的初始缩放级别1表示 100%原始大小。zoomRange[number, number]默认值:[0.01, 10]缩放范围限制用户可以缩放的最小和最大比例。在视口变换时会通过clamp将缩放值限制在该区间内见 packages/g6/src/runtime/viewport.ts。rotationnumber默认值:0旋转角度以弧度为单位。paddingnumber | number[]画布内边距。通常在自适应autoFit时会根据内边距进行适配。可以是单个数值四边相同或者数组形式按顺序指定上、右、下、左的内边距// 单个数值 const graph1 new Graph({ padding: 20, // 四边均为 20 像素的内边距 }); // 数组形式 const graph2 new Graph({ padding: [20, 40, 20, 40], // 上、右、下、左的内边距 });在fitView的实现中内边距会从视口尺寸中扣除作为内容可用的有效区域见 packages/g6/src/runtime/viewport.ts。autoFit{ type: view; options?: FitViewOptions; animation?: ViewportAnimationEffectTiming } | { type: center; animation?: ViewportAnimationEffectTiming } | view | center是否自动适应画布。⚠️ 注意每次执行render时都会根据autoFit进行自适应见 packages/g6/src/spec/viewport.ts 中的 remarks。两种基本自适应模式view— 自动缩放确保所有内容都在视图内可见center— 内容居中显示但不改变缩放比例还可通过对象形式实现更精细的自适应控制const graph new Graph({ autoFit: { type: view, // 自适应类型view 或 center options: { // 仅适用于 view 类型 when: overflow, // 何时适配overflow(仅当内容溢出时) 或 always(总是适配) direction: x, // 适配方向x、y 或 both }, animation: { // 自适应动画效果 duration: 1000, // 动画持续时间(毫秒) easing: ease-in-out, // 动画缓动函数 }, }, });FitViewOptions属性描述类型默认值必选when在以下情况下进行适配-overflow仅当图内容超出视口时进行适配-always总是进行适配overflow|alwaysalwaysdirection仅对指定方向进行适配-x仅适配 x 方向-y仅适配 y 方向-both适配 x 和 y 方向x|y|bothbothViewportAnimationEffectTimingtype ViewportAnimationEffectTiming | boolean // true 启用默认动画false 禁用动画 | { easing?: string; // 动画缓动函数ease-in-out、ease-in、ease-out、linear duration?: number; // 动画持续时间(毫秒) };全局动画animationboolean | AnimationEffectTiming启用或关闭全局动画。为动画配置项时会启用动画并将该动画配置作为全局动画的基础配置见 packages/g6/src/spec/graph.ts。AnimationEffectTiming属性描述类型默认值必选delay动画延迟时间number-direction动画方向alternate|alternate-reverse|normal|reverseforwardduration动画持续时间number-easing动画缓动函数string-fill动画结束后的填充模式auto|backwards|both|forwards|nonenoneiterations动画迭代次数number-示例// 简单启用 const graph1 new Graph({ animation: true, }); // 详细配置 const graph2 new Graph({ animation: { duration: 500, // 动画持续时间毫秒 easing: ease-in-out, // 缓动函数 }, });数据dataGraphData数据字段接受{ nodes, edges, combos }三部分其中nodes与edges为必选GraphData属性描述类型默认值必选nodes节点数据NodeData[]-✓edges边数据EdgeData[]-✓combos组合数据ComboData[]-NodeData属性描述类型默认值必选id节点的唯一标识符用于区分不同的节点string-✓type节点类型内置节点类型名称或者自定义节点的名称string-data节点数据用于存储节点的自定义数据例如节点的名称、描述等。可以在样式映射中通过回调函数获取object-style节点样式包括位置、大小、颜色等视觉属性object-states节点初始状态如选中、激活、悬停等string[]-combo所属的组合 ID用于组织节点的层级关系如果没有则为 nullstring | null-children子节点 ID 集合仅在树图场景下使用string[]-EdgeData属性描述类型默认值必选source边起始节点 IDstring-✓target边目标节点 IDstring-✓id边的唯一标识符string-type边类型内置边类型名称或者自定义边的名称string-data边数据用于存储边的自定义数据可以在样式映射中通过回调函数获取object-style边样式包括线条颜色、宽度、箭头等视觉属性object-states边初始状态string[]-ComboData属性描述类型默认值必选id组合的唯一标识符string-✓type组合类型内置组合类型名称或者自定义组合名称string-data组合数据用于存储组合的自定义数据可以在样式映射中通过回调函数获取object-style组合样式object-states组合初始状态string[]-combo组合的父组合 ID。如果没有父组合则为 nullstring | null-示例const graph new Graph({ data: { nodes: [ { id: node1, style: { x: 100, y: 100 } }, { id: node2, style: { x: 200, y: 200 } }, ], edges: [{ id: edge1, source: node1, target: node2 }], combos: [{ id: combo1, style: { x: 150, y: 150 } }], }, });更多关于数据格式与数据操作的细节可查阅仓库内 数据文档 与 数据 API。元素配置node / edge / combo节点、边、组合三类元素在 GraphOptions 中共享一套「类型 样式 状态 色板 动画」的配置结构。NodeOptions属性描述类型默认值必选type节点类型内置节点类型名称或自定义节点的名称Typecirclestyle节点样式包括颜色、大小等Style-state定义节点在不同状态下的样式State-palette定义节点的色板用于根据不同数据映射颜色Palette-animation定义节点的动画效果Animation-const graph new Graph({ node: { type: circle, // 节点类型 style: { fill: #e6f7ff, // 填充色 stroke: #91d5ff, // 边框色 lineWidth: 1, // 边框宽度 r: 20, // 半径 labelText: (d) d.id, // 标签文本回调形式可读取节点数据 }, // 节点状态样式 state: { hover: { lineWidth: 2, stroke: #69c0ff, }, selected: { fill: #bae7ff, stroke: #1890ff, lineWidth: 2, }, }, }, });EdgeOptions默认类型为lineconst graph new Graph({ edge: { type: polyline, // 边类型内置line / polyline / quadratic / cubic / cubic-horizontal / cubic-vertical / cubic-radial / loop style: { stroke: #91d5ff, // 边的颜色 lineWidth: 2, // 边的宽度 endArrow: true, // 是否有箭头 }, // 边的状态样式 state: { selected: { stroke: #1890ff, lineWidth: 3, }, }, }, });ComboOptions默认类型为circleconst graph new Graph({ combo: { type: circle, // 组合类型 style: { fill: #f0f0f0, // 背景色 stroke: #d9d9d9, // 边框色 lineWidth: 1, // 边框宽度 }, // 组合状态样式 state: { selected: { stroke: #1890ff, lineWidth: 2, }, }, }, });三类元素各自的类型定义位于 packages/g6/src/spec/element内置元素实现位于 packages/g6/src/elements/nodes、packages/g6/src/elements/edges 与 packages/g6/src/elements/combos。布局layoutCustomLayoutOptions | CustomLayoutOptions[]布局配置项可以是对象普通布局或数组流水线布局多个布局依次执行。const graph new Graph({ container: container, layout: { type: force, // 力导向布局 preventOverlap: true, // 防止节点重叠 nodeStrength: -50, // 节点之间的斥力 edgeStrength: 0.5, // 边的弹性系数 iterations: 200, // 迭代次数 animation: true, // 启用布局动画 }, });如前述当 layout 为单个对象且类型属于推断列表时框架会自动注入preLayout: true见 packages/g6/src/runtime/options.ts。完整的布局类型定义见 packages/g6/src/spec/layout.ts内置布局实现见 packages/g6/src/layouts。主题themefalse | light | dark | string设置图表的主题可以是内置的light、dark主题也可以是自定义主题的名称。设为false则不使用任何主题。内置主题的实现位于 packages/g6/src/themes包含 light.ts 与 dark.ts 两套预设。交互行为behaviors(string | CustomExtensionOptions | ((this: Graph) CustomExtensionOptions))[]配置图表的交互行为可以是字符串使用默认配置、对象自定义配置或函数动态配置、函数内可访问图实例const graph new Graph({ behaviors: [ drag-canvas, // 使用默认配置启用画布拖拽 zoom-canvas, // 使用默认配置启用画布缩放 { type: drag-element, // 自定义配置拖拽元素 key: drag-node-only, enable: (event) event.targetType node, // 只允许拖拽节点 }, function () { console.log(this); // 输出 graph 实例 return { type: hover-activate, }; }, ], });注意setOptions({ behaviors })会全量替换原有交互配置。如果需要新增一个交互而不影响已有交互推荐使用setBehaviors((behaviors) [...behaviors, { type: zoom-canvas }])的函数式写法见 packages/g6/src/runtime/graph.ts若要更新单个交互则需在配置中给该交互指定key再通过updateBehavior({ key, ...patch })定向更新。内置交互实现位于 packages/g6/src/behaviors。插件plugins(string | CustomExtensionOptions | ((this: Graph) CustomExtensionOptions))[]设置图表的插件配置形态与 behaviors 一致const graph new Graph({ container: container, plugins: [ minimap, // 启用小地图使用默认配置 { type: grid, // 启用网格背景 key: grid-plugin, line: { stroke: #d9d9d9, lineWidth: 1, }, }, { type: toolbar, // 启用工具栏 key: graph-toolbar, position: top-right, // 位置 }, ], });同样地setOptions({ plugins })是全量替换新增插件可用setPlugins((plugins) [...plugins, { key: grid-line }])定向更新用updatePlugin({ key, ...patch })。部分插件实例暴露了可直接调用的 API可通过graph.getPluginInstance(key)获取实例后调用如全屏插件的request()/exit()见 packages/g6/src/runtime/graph.ts。内置插件实现位于 packages/g6/src/plugins。数据转换器transforms(string | CustomExtensionOptions | ((this: Graph) CustomExtensionOptions))[]配置数据处理用于在渲染前对数据进行处理不会影响原始数据const graph new Graph({ transforms: [ process-parallel-edges, // 处理平行边使用默认配置 { type: map-node-size, // 根据节点数据映射节点大小 field: value, // 使用 value 字段的值 max: 50, // 最大半径 min: 20, // 最小半径 }, ], });内置数据转换器实现位于 packages/g6/src/transforms包括map-node-size、process-parallel-edges、place-radial-labels、arrange-draw-order、collapse-expand-combo、collapse-expand-node、get-edge-actual-ends、update-related-edge等。扩展配置基类CustomExtensionOptions字符串、对象、函数三种形态最终都归一化为如下结构其中key是扩展的唯一标识用于后续定向更新updateBehavior/updatePlugin/updateTransforminterface CustomExtensionOption extends Recordstring, any { /** 拓展类型 */ type: string; /** 拓展 key即唯一标识 */ key?: string; }实战建议何时用 setOptions何时重建实例综合上文可给出如下决策参考画布级参数container、devicePixelRatio、enableMultiLayer只能在new Graph()时指定运行时修改无效需要销毁重建视口级参数zoom、zoomRange、rotation、padding、autoFit运行时通过setOptions更新后配合render()或视口 API 即可生效主题 / 布局 / 元素样式 / 数据setOptions是首选方案它会自动分发到对应 setter 并触发数据刷新无需重建行为 / 插件 / 转换器setOptions全量替换语义明确新增或定向更新请配合key使用函数式 setter 或updateXxx系列方法。如果需要以编程方式查看当前生效的完整配置随时调用graph.getOptions()该返回值与setOptions的入参结构一致可以「先读取、后修改、再写回」的方式实现精细的配置继承与热更新。【免费下载链接】G6♾ A Graph Visualization Framework in JavaScript.项目地址: https://gitcode.com/gh_mirrors/g6/G6创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
