G6 交互（Behavior）API 完全指南：getBehaviors / setBehaviors / updateBehavior 详解

• 数据可视化
• 前端
• 图表库

导读

交互（Behavior）是 G6 图可视化框架的核心构建模块，它精确定义了用户与图之间的互动行为，例如拖拽画布、缩放视图、框选节点、点击选中等。本文以 G6 官方 API 文档为主线，完整讲解Graph.getBehaviors()、Graph.setBehaviors()、Graph.updateBehavior()三个核心方法的签名、参数与实战示例，并结合 behavior.ts 类型定义与 runtime/graph.ts 源码实现，深入剖析交互配置的底层工作机制。读完本文，你将掌握如何在 G6 中声明、替换、增量更新、禁用/启用各类交互，并能熟练运用key唯一标识与函数式更新等进阶技巧。

交互概述：Behavior 在 G6 中的定位

在 G6 中，每个 Behavior 都是一个高度封装的功能单元，内部集成了特定场景下的事件监听、状态管理和响应处理逻辑。从源码结构看，所有内置交互都继承自 BaseBehavior 抽象基类，并通过 behaviors/index.ts 统一导出。目前仓库内置了 16 种常用交互：

说明：tooltip、legend、minimap等能力在 G6 中属于 Plugin（插件）而非 Behavior，可通过 plugins 文档 查阅。

G6 的内置 Behavior 涵盖了大多数常见交互需求，同时提供了灵活的扩展机制，支持开发者基于BaseBehavior构建定制化交互体验。关于交互的设计哲学与自定义扩展方法，可参阅 交互总览 系列文档。

API 参考

Graph.getBehaviors()：获取当前全部交互

获取当前图表中所有已配置的交互行为。

getBehaviors(): BehaviorOptions;

返回值

• 类型：BehaviorOptions
• 描述：当前图表中已配置的所有交互行为

示例

// 获取当前所有交互行为 const behaviors = graph.getBehaviors(); console.log('当前图表的交互行为:', behaviors);

从源码看，getBehaviors()的实现非常直接——直接返回配置对象中保存的交互列表，未配置时返回空数组（见 runtime/graph.ts）：

public getBehaviors(): BehaviorOptions { return this.options.behaviors || []; }

该方法常与函数式更新配合使用，作为setBehaviors回调的入参来源。

Graph.setBehaviors(behaviors)：设置交互（全量替换）

设置图表的交互行为，将替换所有现有的交互行为。

setBehaviors(behaviors: BehaviorOptions | ((prev: BehaviorOptions) => BehaviorOptions)): void;

参数

说明

设置的交互会全量替换原有的交互，如果需要新增交互可以使用函数式更新：

graph.setBehaviors((behaviors) => [...behaviors, { type: 'zoom-canvas' }]);

结合 runtime/graph.ts 的实现可以看到，setBehaviors首先将新配置（或函数计算结果）写回options.behaviors，再交给BehaviorController实际生效：

public setBehaviors(behaviors: BehaviorOptions | ((prev: BehaviorOptions) => BehaviorOptions)): void { this.options.behaviors = isFunction(behaviors) ? behaviors(this.getBehaviors()) : behaviors; this.context.behavior?.setBehaviors(this.options.behaviors); }

示例 1：设置基本交互

// 设置基本交互 graph.setBehaviors([ 'drag-canvas', // 拖拽画布 'zoom-canvas', // 缩放画布 'drag-element', // 拖拽元素 ]);

示例 2：设置带配置的交互

graph.setBehaviors([ // 字符串形式（使用默认配置） 'drag-canvas', // 对象形式（自定义配置） { type: 'zoom-canvas', key: 'my-zoom', // 指定唯一标识，用于后续更新 sensitivity: 1.5, // 缩放灵敏度 }, // 只有节点上启用拖拽 { type: 'drag-element', key: 'drag-node-only', enable: (event) => event.targetType === 'node', // 仅在节点上启用拖拽 }, ]);

示例 3：使用函数式更新

// 添加新的交互行为 graph.setBehaviors((currentBehaviors) => [ ...currentBehaviors, { type: 'brush-select', key: 'selection-brush', }, ]); // 替换特定交互行为 graph.setBehaviors((currentBehaviors) => { // 过滤掉现有的缩放交互 const filteredBehaviors = currentBehaviors.filter((behavior) => { if (typeof behavior === 'string') return behavior !== 'zoom-canvas'; return behavior.type !== 'zoom-canvas'; }); // 添加新的缩放交互配置 return [ ...filteredBehaviors, { type: 'zoom-canvas', key: 'new-zoom', enableOptimize: true, }, ]; });

Graph.updateBehavior(behavior)：精确更新单个交互

更新指定的交互行为配置，需要通过key标识要更新的交互。

updateBehavior(behavior: UpdateBehaviorOption): void;

参数

说明

如果要更新一个交互，必须在原始交互配置中指定key字段，以便能够准确找到并更新该交互。

从 runtime/graph.ts 的实现可以看到，updateBehavior内部借助函数式setBehaviors完成"按 key 查找 + 配置合并"：

public updateBehavior(behavior: UpdateBehaviorOption): void { this.setBehaviors((behaviors) => behaviors.map((_behavior) => { if (typeof _behavior === 'object' && _behavior.key === behavior.key) { return { ..._behavior, ...behavior }; } return _behavior; }), ); }

即：遍历现有交互列表，凡是对象形式且key匹配的配置，就用新配置做浅合并（{ ..._behavior, ...behavior }）；字符串形式的配置项因没有key，不会参与匹配。这也是文档反复强调"必须先指定key"的根本原因。

示例 1：更新交互配置

// 初始设置交互时指定 key graph.setBehaviors([ { type: 'zoom-canvas', key: 'my-zoom-canvas', sensitivity: 1.0, }, ]); // 更新交互配置 graph.updateBehavior({ key: 'my-zoom-canvas', // 指定要更新的交互 sensitivity: 2.0, // 新的缩放灵敏度 enableOptimize: true, // 添加新配置 });

示例 2：禁用 / 启用交互

// 设置带 key 的行为 graph.setBehaviors([ { type: 'drag-canvas', key: 'main-drag', }, { type: 'zoom-canvas', key: 'main-zoom', }, ]); // 禁用拖拽功能 graph.updateBehavior({ key: 'main-drag', enable: false, }); // 稍后重新启用 setTimeout(() => { graph.updateBehavior({ key: 'main-drag', enable: true, }); }, 5000);

enable是几乎所有内置交互都支持的通用开关，既可以是布尔值，也可以是(event) => boolean函数，函数返回false时本次交互不响应（例如仅在节点上启用拖拽、仅在特定元素类型上响应点击）。各交互的完整配置项请查看对应源码中的 Options 接口，例如 zoom-canvas.ts 中的ZoomCanvasOptions（animation、origin、trigger、sensitivity等）与 drag-element.ts 中的DragElementOptions（dropEffect、state、shadow、trigger等）。

类型定义

BehaviorOptions

type BehaviorOptions = (string | CustomBehaviorOption | ((this: Graph) => CustomBehaviorOption))[]; type CustomBehaviorOption = { // 交互类型 type: string; // 交互 key，即唯一标识，用于标识交互，从而进一步操作此交互 key?: string; // 针对不同类型的交互，还可能有其他配置项 [configKey: string]: any; };

该类型定义与源码 spec/behavior.ts 完全一致。三种合法元素：

• 字符串形式（如'drag-canvas'）：使用该交互的全部默认配置；
• 对象形式（CustomBehaviorOption）：type必填，key可选但推荐填写（更新、禁用时必需），其余字段为对应交互的配置项；
• 函数形式（(this: Graph) => CustomBehaviorOption）：返回一个交互配置对象，this指向当前Graph实例，可用于根据图状态动态计算配置。

UpdateBehaviorOption

type UpdateBehaviorOption = { // 要更新的交互的唯一标识 key: string; // 其他要更新的配置项 [configKey: string]: unknown; };

key为必填项，其余字段将浅合并进目标交互的现有配置中。注意UpdateBehaviorOption本身不含type——更新时不能更换交互类型，只能调整现有实例的配置。

底层原理：交互如何被创建、更新与销毁

扩展控制器：基于 diff 的增量管理

setBehaviors最终会走到 registry/extension/index.ts 中ExtensionController.setExtensions()。它并非简单地"全部重建"，而是先通过arrayDiff计算新旧配置的差异，分为四类后分别处理：

const { enter, update, exit, keep } = arrayDiff(this.extensions, stdExtensions, (extension) => extension.key); this.createExtensions(enter); // 新增的交互 -> 创建实例 this.updateExtensions([...update, ...keep]); // 保留的交互 -> 更新配置 this.destroyExtensions(exit); // 消失的交互 -> 销毁实例

• createExtension：从注册表中按type获取构造函数（getExtension(category, type)），实例化并存入extensionMap，以key为索引；
• updateExtension：对已存在的实例调用instance.update(extension)，将新配置Object.assign进实例的options；
• destroyExtension：调用instance.destroy()并清理事件监听。

这套机制保证了重复调用setBehaviors时，key相同的交互实例会被复用而非反复重建，既保留了交互内部状态，也避免了无谓的创建/销毁开销。这也解释了为什么updateBehavior能实现"禁用 / 启用"——它本质上是通过函数式setBehaviors生成了配置变更，再由 diff 机制精准地只更新对应实例。

事件转发：交互如何感知用户操作

交互本身不直接监听 DOM，而是由 runtime/behavior.ts 中的BehaviorController统一转发事件。它在构造函数中为画布容器与画布 document 注册了大量监听器：

• 容器（container）监听keydown、keyup，用于支持快捷键类交互（如zoom-canvas的Control + 滚轮组合键）；
• 画布（document）监听click、dblclick、pointerdown/up/move/enter/leave/over/out、contextmenu、drag*、drop、wheel等事件。

事件到达后，forwardCanvasEvents会做三件事：

1. 通过eventTargetOf解析出真实的事件目标元素与targetType（'node'/'edge'/'combo'/'canvas'等），跳过已销毁元素；
2. 将pointermove派生出pointerenter/pointerleave，维护currentTarget状态；
3. 按${targetType}:${type}与全局type两种粒度通过graph.emit广播事件，右键按下还会派生出contextmenu事件。

每个 Behavior 实例在自己的bindEvents中订阅这些事件并执行逻辑，最终构成"用户操作 → 事件转发 → 交互响应"的完整闭环。G6 的测试套件对此有大量验证，例如 behaviors-click-select.spec.ts、behaviors-drag-element-combo.spec.ts、behaviors-drag-rotated-canvas.spec.ts 等，覆盖了点击选中、拖拽 Combo、旋转画布后拖拽等真实场景。

常见实战问题

Q1：为什么updateBehavior没有生效？绝大多数情况是因为原始配置未指定key。updateBehavior只匹配对象形式且key相等的配置（见上文源码），字符串形式配置无法被定位。请在setBehaviors时为每个需要动态更新的交互显式设置key。

Q2：如何只新增一个交互而不影响已有交互？使用函数式写法graph.setBehaviors((behaviors) => [...behaviors, { type: 'xxx' }])，回调中的behaviors即getBehaviors()返回的当前配置。

Q3：如何动态禁用某个交互？保持key不变，调用graph.updateBehavior({ key, enable: false })；需要时再以enable: true恢复。enable也可传函数实现按事件条件动态放行。

Q4：交互与插件（Plugin）如何区分？Behavior 处理"用户输入 → 图状态"的互动（拖拽、缩放、选择等），Plugin 负责独立的功能模块（tooltip、legend、minimap、hull 等）。两者均通过扩展机制注册，但所属分类（category）不同，管理 API 也相互独立（setBehaviors/setPlugins）。

小结

本文完整覆盖了 G6 交互体系的三个核心 API：getBehaviors()负责读取、setBehaviors()负责全量设置（支持字符串 / 对象 / 函数三种配置形式与函数式增量更新）、updateBehavior()负责基于key的精准更新（含禁用 / 启用）。结合 spec/behavior.ts 的类型定义、runtime/graph.ts 的方法实现以及 registry/extension/index.ts 的 diff 管理机制，你可以深入理解交互配置从"声明"到"实例化生效"的完整链路，从而在业务中灵活组合、动态调整交互，构建出贴合场景的图应用交互体验。

• 数据可视化
• 前端
• 图表库