G6 边过滤镜插件 EdgeFilterLens 完全指南:配置、原理与实战
G6 边过滤镜插件 EdgeFilterLens 完全指南:配置、原理与实战
边过滤镜(EdgeFilterLens)是 G6 图形可视化框架内置的交互式探索插件,它以一个可移动的圆形透镜罩住画布局部区域,只在该区域内保留与焦点相关的边,从而帮助用户在密集的复杂网络中快速聚焦局部边关系。本文将围绕 edge-filter-lens.md 的完整配置示例展开,并结合 插件源码、单元测试 与 官方手册,从零开始带你掌握该插件的全部配置项、事件机制与底层实现原理,并提供一个可直接复制运行的完整图例。
功能概述:透镜之内,只留关注的边
在节点稠密、边交叉严重的图数据中,直接阅读整张图往往非常吃力。EdgeFilterLens 提供了一种“聚焦式”的解决方案:
边过滤镜可以将关注的边保留在过滤镜范围内,其他边将在该范围内不显示。
其核心交互体验是:一个圆形透镜跟随鼠标(或点击、拖拽)在画布上移动,透镜内部的节点会被“点亮”并放大,同时根据 nodeType 规则决定哪些边显示出来。这样既保留了上下文位置感,又屏蔽了无关连线,是复杂网络可视化中常用的局部探索工具。
典型适用场景包括:
- 需要聚焦查看局部区域的边关系(如社交网络中某个社区的连接结构);
- 在复杂网络中突出显示特定节点之间的连接,弱化背景噪声;
- 作为图分析、关系排查、业务链路梳理时的辅助洞察工具。
该插件随 G6 内置发布,在 插件统一入口 中导出 EdgeFilterLens 类,并通过 内置扩展注册表 注册为 'edge-filter-lens' 类型,因此无需额外安装即可直接通过 plugins 配置项启用。
快速上手:两行配置启用插件
最简用法只需要在 new Graph() 的 plugins 数组中声明插件类型即可:
const graph = new Graph({
// ...data, node, edge 等配置
plugins: ['edge-filter-lens'],
});
graph.render();
启用后插件即按默认配置工作:透镜半径 60、跟随鼠标移动、nodeType 为 'both'(两端节点都在透镜内才显示边)。仓库中的 单元测试演示 使用的正是这种零参数初始化方式:
import data from '@@/dataset/relations.json';
import { Graph } from '@antv/g6';
export const pluginEdgeFilterLens: TestCase = async (context) => {
const graph = new Graph({
...context,
data,
node: {
style: { size: 16 },
palette: {
field: (datum) => Math.floor(Number(datum.style?.y) / 60),
},
},
edge: {
style: {
label: false,
labelText: (d) => d.data!.value?.toString(),
stroke: '#ccc',
},
},
plugins: [
{
key: 'edge-filter-lens',
type: 'edge-filter-lens',
},
],
autoFit: 'view',
});
await graph.render();
return graph;
};
配置项详解:从默认值到取值语义
插件支持通过对象形式传入 EdgeFilterLensOptions,其完整类型定义见 edge-filter-lens/index.ts,各配置项整理如下:
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
type |
插件类型,固定为 'edge-filter-lens' |
string |
edge-filter-lens |
key |
插件的唯一标识,用于获取插件实例或通过 updatePlugin 更新选项 |
string |
- |
trigger |
移动透镜的方式:pointermove(跟随鼠标)/ click(点击画布时移动到点击位置)/ drag(拖拽移动透镜) |
'pointermove' | 'click' | 'drag' |
'pointermove' |
r |
透镜的半径(像素) | number |
60 |
maxR |
透镜最大半径,仅在 scaleRBy 为 'wheel' 时生效 |
number |
画布宽高最小值的一半 |
minR |
透镜最小半径,仅在 scaleRBy 为 'wheel' 时生效 |
number |
0 |
scaleRBy |
缩放透镜半径的方式,目前支持 'wheel'(滚轮缩放) |
'wheel' |
'wheel' |
nodeType |
边显示条件:both(起止节点都在透镜内)/ source(仅起始节点在透镜内)/ target(仅目标节点在透镜内)/ either(起止节点任一在透镜内) |
'both' | 'source' | 'target' | 'either' |
'both' |
filter |
过滤掉永远不在透镜中显示的元素(节点 / 边 / combo) | (id, elementType) => boolean |
() => true |
style |
透镜圆形本身的样式(CircleStyleProps) | Partial<CircleStyleProps> |
{ lineWidth: 2 } |
nodeStyle |
透镜内节点的样式 | NodeStyle | (datum) => NodeStyle |
{ label: false } |
edgeStyle |
透镜内边的样式 | EdgeStyle | (datum) => EdgeStyle |
{ label: true } |
preventDefault |
是否阻止默认事件(滚轮缩放时阻止页面滚动) | boolean |
true |
上述默认值可以在 EdgeFilterLens 类的 defaultOptions 中直接核对:
static defaultOptions: Partial<EdgeFilterLensOptions> = {
trigger: 'pointermove',
r: 60,
nodeType: 'both',
filter: () => true,
style: { lineWidth: 2 },
nodeStyle: { label: false },
edgeStyle: { label: true },
scaleRBy: 'wheel',
preventDefault: true,
};
trigger:三种透镜移动方式
trigger 决定透镜如何定位,源码中 bindEvents 根据其取值绑定不同事件:
'pointermove':监听画布的pointermove事件,透镜始终跟随鼠标指针移动(默认行为);'click':监听画布的click事件,仅在鼠标点击时把透镜移动到点击位置;'drag':同时监听click、dragstart、drag、dragend事件——先用点击“召唤”透镜,之后按住透镜内部拖拽移动。
注意 drag 模式下 onEdgeFilter 有一个前置判断:if (this.options.trigger === 'drag' && this.isLensOn) return;,即透镜已存在时点击不再重新定位,避免与拖拽手势冲突。
r / minR / maxR / scaleRBy:半径与滚轮缩放
r是透镜当前半径,可直接指定;- 当
scaleRBy为'wheel'时,滚轮可以实时缩放透镜。缩放的底层逻辑见 scaleRByWheel:- 只有当鼠标指针位于透镜内部(与圆心距离小于
r)时缩放才生效; - 每次滚轮以固定增量
DELTA = 0.05等比缩放:this.r * (1 - DELTA)(放大)或this.r / (1 - DELTA)(缩小); - 缩放结果被限制在
minR与maxR之间,其中maxR未配置时取Math.min(...canvas.getSize()) / 2,即画布宽高最小值的一半; - 由于滚轮监听是绑定在 DOM 上并以
{ passive: false }方式注册,配合preventDefault: true可以阻止滚轮事件导致页面滚动。
- 只有当鼠标指针位于透镜内部(与圆心距离小于
nodeType:边的显示判定规则
这是插件最核心的语义配置。在 getFocusElements 中,插件先筛出与透镜圆心距离小于 r 的节点作为 focusNodes,再按 nodeType 对每条边做判定:
const focusEdges = edges.filter((datum) => {
const { source, target } = datum;
const isSourceFocus = focusNodeIds.includes(source);
const isTargetFocus = focusNodeIds.includes(target);
switch (this.options.nodeType) {
case 'both':
return isSourceFocus && isTargetFocus;
case 'either':
return isSourceFocus !== isTargetFocus;
case 'source':
return isSourceFocus && !isTargetFocus;
case 'target':
return !isSourceFocus && isTargetFocus;
default:
return false;
}
});
'both':起始节点和目标节点都在透镜内才显示该边(默认),最严格,适合查看“透镜内完整的连通子图”;'source':仅起始节点在透镜内就显示,适合追溯“从这里出发的边”;'target':仅目标节点在透镜内就显示,适合查看“指向这里的边”;'either':两端任一在透镜内即显示,最宽松,适合观察局部邻域。
filter:全局排除元素
filter 是一个 (id: ID, elementType: 'node' | 'edge' | 'combo') => boolean 回调,返回 false 的元素在任何情况下都不会被透镜高亮显示。它作用于数据模型层,见 getFilterData,会同时过滤 nodes、edges 与 combos 三类数据。可用于排除噪音节点、隐藏指定业务边等场景。
style:透镜外观
透镜本身是一个圆形(Circle 元素),叠加在 transient 临时图层上。除默认值 { lineWidth: 2 } 外,插件内部还维护一套兜底样式 defaultLensStyle:
const defaultLensStyle: Exclude<CircleStyleProps, 'r'> = {
fill: '#fff',
fillOpacity: 1,
lineWidth: 1,
stroke: '#000',
strokeOpacity: 0.8,
zIndex: -Infinity,
};
最终渲染时 Object.assign({}, defaultLensStyle, this.options.style) 合并二者,因此你只需覆盖关心字段即可。常用样式属性包括:
| 属性 | 描述 | 默认值 |
|---|---|---|
fill |
填充颜色 | #fff |
stroke |
描边颜色 | #000 |
opacity |
整体透明度 | 1 |
fillOpacity |
填充透明度 | 0.8 |
strokeOpacity |
描边透明度 | - |
lineWidth |
线宽 | 2(合并默认值后) |
lineCap |
线段端点样式 | - |
lineJoin |
线段连接处样式 | - |
shadowColor / shadowBlur / shadowOffsetX / shadowOffsetY |
阴影系列 | - |
nodeStyle / edgeStyle:透镜内元素样式
透镜内的节点与边并非直接操作原图元素,而是克隆原元素到临时图层后叠加样式(见下文渲染原理)。nodeStyle 与 edgeStyle 均支持两种形态:
- 静态样式对象,如
{ size: 24, fill: '#7e3feb' }; - 函数形态
(datum) => NodeStyle / EdgeStyle,可按数据动态返回样式,例如测试中用到的edgeStyle: () => ({ stroke: '#f00' })。
样式解析逻辑见 getElementStyle。默认值 nodeStyle: { label: false } 表示透镜内默认不显示节点标签(避免遮挡),edgeStyle: { label: true } 表示透镜内的边默认显示标签。
渲染原理:克隆元素 + 临时图层
理解这个插件的实现,能帮助你更准确地预估它在复杂场景下的表现。核心流程在 renderFocusElements 中:
- 通过
context.canvas.getLayer('transient')获取临时图层,透镜 Circle 与其内部的高亮元素都绘制在这一层; - 对每个进入透镜范围的元素,调用
shape.cloneNode()克隆一份副本,设置与原始元素相同的位置与 id,追加到临时图层; - 遍历原始元素的 attributes,把发生变化的样式同步到克隆体,再叠加
nodeStyle/edgeStyle; - 当元素离开透镜范围时,销毁对应克隆体并从
shapes缓存中移除。
这种“克隆到临时层”的机制保证:透镜高亮不影响原始图元状态,退出透镜后一切恢复原状,且透镜可以跟随指针高频重绘而不会污染主画布。
完整实战示例:Les Misérables 关系图上的边过滤镜
下面是一个完整、可直接运行的示例(源自 关联文档 的在线演示),使用《悲惨世界》人物关系数据构造了多块密度不同的区域,并配置了半径 80、跟随鼠标移动的边过滤镜:
createGraph(
{
data: {
nodes: [
// 上部疏散区域
{ id: 'Myriel', style: { x: 207, y: 78, label: 'Myriel' } },
{ id: 'Napoleon', style: { x: 127, y: 62, label: 'Napoleon' } },
{ id: 'CountessdeLo', style: { x: 171, y: 47, label: 'CountessdeLo' } },
{ id: 'Geborand', style: { x: 106, y: 81, label: 'Geborand' } },
{ id: 'Champtercier', style: { x: 247, y: 58, label: 'Champtercier' } },
{ id: 'Cravatte', style: { x: 152, y: 50, label: 'Cravatte' } },
// 中上部区域
{ id: 'Mlle.Baptistine', style: { x: 205, y: 141, label: 'Mlle.Baptistine' } },
{ id: 'Mme.Magloire', style: { x: 275, y: 120, label: 'Mme.Magloire' } },
{ id: 'Labarre', style: { x: 246, y: 183, label: 'Labarre' } },
{ id: 'Valjean', style: { x: 342, y: 221, label: 'Valjean' } },
{ id: 'Marguerite', style: { x: 285, y: 171, label: 'Marguerite' } },
// 中部密集区域
{ id: 'Tholomyes', style: { x: 379, y: 158, label: 'Tholomyes' } },
{ id: 'Listolier', style: { x: 288, y: 80, label: 'Listolier' } },
{ id: 'Fameuil', style: { x: 349, y: 89, label: 'Fameuil' } },
{ id: 'Blacheville', style: { x: 381, y: 95, label: 'Blacheville' } },
{ id: 'Favourite', style: { x: 264, y: 153, label: 'Favourite' } },
{ id: 'Dahlia', style: { x: 323, y: 170, label: 'Dahlia' } },
{ id: 'Zephine', style: { x: 306, y: 114, label: 'Zephine' } },
{ id: 'Fantine', style: { x: 357, y: 187, label: 'Fantine' } },
// 右侧区域
{ id: 'Bamatabois', style: { x: 411, y: 156, label: 'Bamatabois' } },
{ id: 'Perpetue', style: { x: 454, y: 195, label: 'Perpetue' } },
{ id: 'Simplice', style: { x: 406, y: 227, label: 'Simplice' } },
// 下部区域
{ id: 'Cosette', style: { x: 343, y: 248, label: 'Cosette' } },
{ id: 'Javert', style: { x: 388, y: 263, label: 'Javert' } },
{ id: 'Fauchelevent', style: { x: 397, y: 276, label: 'Fauchelevent' } },
{ id: 'Thenardier', style: { x: 317, y: 300, label: 'Thenardier' } },
{ id: 'Eponine', style: { x: 268, y: 365, label: 'Eponine' } },
{ id: 'Anzelma', style: { x: 234, y: 303, label: 'Anzelma' } },
{ id: 'Woman2', style: { x: 304, y: 254, label: 'Woman2' } },
// 最右侧独立节点
{ id: 'Gribier', style: { x: 457, y: 160, label: 'Gribier' } },
{ id: 'Jondrette', style: { x: 510, y: 327, label: 'Jondrette' } },
],
edges: [
// 上部连接
{ id: 'e1', source: 'Myriel', target: 'CountessdeLo' },
{ id: 'e2', source: 'Napoleon', target: 'Myriel' },
{ id: 'e3', source: 'Geborand', target: 'Napoleon' },
{ id: 'e4', source: 'Champtercier', target: 'Myriel' },
{ id: 'e5', source: 'Cravatte', target: 'CountessdeLo' },
// 中上部连接
{ id: 'e6', source: 'Mlle.Baptistine', target: 'Mme.Magloire' },
{ id: 'e7', source: 'Labarre', target: 'Valjean' },
{ id: 'e8', source: 'Valjean', target: 'Marguerite' },
{ id: 'e9', source: 'Marguerite', target: 'Mme.Magloire' },
// 中部密集连接
{ id: 'e10', source: 'Tholomyes', target: 'Listolier' },
{ id: 'e11', source: 'Listolier', target: 'Fameuil' },
{ id: 'e12', source: 'Fameuil', target: 'Blacheville' },
{ id: 'e13', source: 'Blacheville', target: 'Favourite' },
{ id: 'e14', source: 'Favourite', target: 'Dahlia' },
{ id: 'e15', source: 'Dahlia', target: 'Zephine' },
{ id: 'e16', source: 'Zephine', target: 'Fantine' },
{ id: 'e17', source: 'Tholomyes', target: 'Fantine' },
{ id: 'e18', source: 'Valjean', target: 'Fantine' },
// 右侧连接
{ id: 'e19', source: 'Bamatabois', target: 'Perpetue' },
{ id: 'e20', source: 'Perpetue', target: 'Simplice' },
{ id: 'e21', source: 'Bamatabois', target: 'Gribier' },
// 下部连接
{ id: 'e22', source: 'Valjean', target: 'Cosette' },
{ id: 'e23', source: 'Cosette', target: 'Javert' },
{ id: 'e24', source: 'Javert', target: 'Fauchelevent' },
{ id: 'e25', source: 'Fauchelevent', target: 'Thenardier' },
{ id: 'e26', source: 'Thenardier', target: 'Eponine' },
{ id: 'e27', source: 'Eponine', target: 'Anzelma' },
{ id: 'e28', source: 'Woman2', target: 'Cosette' },
// 跨区域连接
{ id: 'e29', source: 'Fantine', target: 'Bamatabois' },
{ id: 'e30', source: 'Javert', target: 'Bamatabois' },
{ id: 'e31', source: 'Simplice', target: 'Jondrette' },
{ id: 'e32', source: 'Thenardier', target: 'Jondrette' },
{ id: 'e33', source: 'Favourite', target: 'Valjean' },
{ id: 'e34', source: 'Tholomyes', target: 'Cosette' },
],
},
node: {
style: {
label: true,
size: 16,
},
palette: {
field: (datum) => Math.floor(datum.style?.y / 60),
},
},
edge: {
style: {
label: true,
labelText: (d) => d.data.value?.toString(),
stroke: '#ccc',
endArrow: true,
endArrowType: 'triangle',
},
},
plugins: [
{
type: 'edge-filter-lens',
key: 'edge-filter-lens',
r: 80,
trigger: 'pointermove',
},
],
},
{ width: 600, height: 400 },
);
在浏览器中移动鼠标,你会看到透镜在密集的中部区域快速筛选出局部连通关系,而跨区域的边(如 e29~e34)只有满足 nodeType 条件时才会被点亮。
自定义外观:让透镜融入你的主题
透镜的视觉风格与内部元素样式都可以高度定制。以下配置(源自 官方手册)演示了紫色主题的透镜:
const graph = new Graph({
plugins: [
{
type: 'edge-filter-lens',
r: 80,
style: {
fill: '#f0f5ff', // 透镜区域的填充颜色
fillOpacity: 0.6, // 填充区域的透明度
stroke: '#7e3feb', // 透镜边框改为紫色
strokeOpacity: 0.8, // 边框的透明度
lineWidth: 1.5, // 边框的线宽
},
nodeStyle: {
size: 24, // 放大节点
fill: '#7e3feb', // 紫色填充
stroke: '#5719c9', // 深紫色描边
lineWidth: 1, // 细边框
label: true, // 显示标签
labelFill: '#ffffff', // 白色文字
labelFontSize: 14, // 放大文字
labelFontWeight: 'bold', // 文字加粗
},
edgeStyle: {
stroke: '#8b9baf', // 灰色边
lineWidth: 2, // 加粗边线
label: true, // 显示标签
labelFill: '#5719c9', // 深紫色文字
opacity: 0.8, // 适当的透明度
},
},
],
});
小提示:nodeStyle / edgeStyle 支持函数形态,可结合节点数据实现更精细的差异化高亮,例如按节点类型返回不同颜色。
交互调参与运行时更新
在调试阶段,你可以在页面中挂一个 GUI 面板(如 lil-gui / dat.GUI),把所有配置项暴露出来实时调节。下面这段代码(源自 关联文档 的演示)展示了完整做法:
const TRIGGER_TYPES = ['pointermove', 'click', 'drag'];
const NODE_TYPES = ['both', 'source', 'target', 'either'];
const options = {
type: 'edge-filter-lens',
r: 80, // 透镜半径
trigger: 'pointermove', // 触发方式
nodeType: 'both', // 边显示条件
minR: 50, // 最小半径
maxR: 150, // 最大半径
scaleRBy: 'wheel', // 缩放方式
style: {
fill: '#f0f5ff',
fillOpacity: 0.4,
stroke: '#1d39c4',
strokeOpacity: 0.8,
lineWidth: 1.5,
},
nodeStyle: {
size: 35,
fill: '#d6e4ff',
stroke: '#2f54eb',
lineWidth: 2,
labelFontSize: 14,
labelFontWeight: 'bold',
labelFill: '#1d39c4',
},
edgeStyle: {
stroke: '#1d39c4',
lineWidth: 2,
strokeOpacity: 0.8,
},
};
const optionFolder = gui.addFolder('Edge Filter Lens Options');
optionFolder.add(options, 'type').disable(true);
optionFolder.add(options, 'r', 50, 150, 5);
optionFolder.add(options, 'trigger', TRIGGER_TYPES);
optionFolder.add(options, 'nodeType', NODE_TYPES);
optionFolder.add(options, 'minR', 20, 100, 5);
optionFolder.add(options, 'maxR', 100, 200, 5);
optionFolder.onChange(({ property, value }) => {
if (property.includes('.')) {
const [group, prop] = property.split('.');
graph.updatePlugin({
key: 'edge-filter-lens',
[group]: {
...options[group],
[prop]: value,
},
});
} else {
graph.updatePlugin({
key: 'edge-filter-lens',
[property]: value,
});
}
graph.render();
});
这里的关键 API 是 graph.updatePlugin({ key, ...newOptions }):插件通过 key 定位实例,然后走 update 方法——它会先解绑旧事件、合并新选项、同步半径 r,再重新绑定事件,因此 trigger、r 等参数都能在运行时热切换。r 的最大/最小建议与 minR / maxR 联动设置,保证滚轮缩放始终在合理区间内。
测试验证:行为如何被守护
仓库的 edge-filter-lens 单元测试 覆盖了本插件的全部关键行为,也可作为用法参考:
- pointermove 移动:派发
POINTER_MOVE事件到画布坐标后断言快照,验证透镜跟随鼠标; - click 移动:
updatePlugin将trigger切为'click',点击两次验证透镜换位; - drag 拖拽:依次派发
CLICK、DRAG_START、DRAG、DRAG_END,验证拖拽移动透镜; - wheel 缩放:在 DOM 上派发原生
WheelEvent,先正向滚动(放大)两次、再反向滚动(缩小)四次,验证r按DELTA = 0.05等比变化并受minR/maxR约束; - nodeType 语义:分别切到
'source'、'target'、'either'后点击同一位置,对三种边显示规则逐一做快照断言; - 函数式样式:
edgeStyle: () => ({ stroke: '#f00' })验证函数形态样式的解析。
如果你在项目里修改或扩展该插件,可参考此测试结构补齐回归用例。
源码速览与延伸阅读
- 插件完整实现:packages/g6/src/plugins/edge-filter-lens/index.ts(含选项类型、默认值、事件绑定、半径缩放、克隆渲染全流程)
- 插件导出入口:packages/g6/src/plugins/index.ts
- 内置注册表(
'edge-filter-lens'字符串到类的映射):packages/g6/src/registry/build-in.ts - 演示用例:packages/g6/tests/demos/plugin-edge-filter-lens.ts
- 单元测试:packages/g6/tests/unit/plugins/edge-filter-lens.spec.ts
- 官方手册:packages/site/docs/manual/plugin/EdgeFilterLens.zh.md
- 可运行示例:packages/site/examples/plugin/edge-filter-lens/demo/basic.js
小结
EdgeFilterLens 是 G6 插件体系中轻量但实用的聚焦工具:一个 plugins: ['edge-filter-lens'] 即可启用,通过 trigger 控制交互方式、r / minR / maxR / scaleRBy 控制透镜形态、nodeType 控制边显示语义,再用 style、nodeStyle、edgeStyle 完成视觉定制,配合 key + updatePlugin 实现运行时热调参。掌握它的配置与克隆渲染原理后,你可以在自己的复杂图分析场景中快速搭建出直观、可交互的局部关系洞察能力。