G6 边过滤镜插件 EdgeFilterLens 完全指南:配置、原理与实战

原创2026-09-22 09:47:072,000 阅读
文章标签:数据可视化前端图表库

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 中:

  1. 通过 context.canvas.getLayer('transient') 获取临时图层,透镜 Circle 与其内部的高亮元素都绘制在这一层;
  2. 对每个进入透镜范围的元素,调用 shape.cloneNode() 克隆一份副本,设置与原始元素相同的位置与 id,追加到临时图层;
  3. 遍历原始元素的 attributes,把发生变化的样式同步到克隆体,再叠加 nodeStyle / edgeStyle;
  4. 当元素离开透镜范围时,销毁对应克隆体并从 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' }) 验证函数形态样式的解析。

如果你在项目里修改或扩展该插件,可参考此测试结构补齐回归用例。

源码速览与延伸阅读

小结

EdgeFilterLens 是 G6 插件体系中轻量但实用的聚焦工具:一个 plugins: ['edge-filter-lens'] 即可启用,通过 trigger 控制交互方式、r / minR / maxR / scaleRBy 控制透镜形态、nodeType 控制边显示语义,再用 style、nodeStyle、edgeStyle 完成视觉定制,配合 key + updatePlugin 实现运行时热调参。掌握它的配置与克隆渲染原理后,你可以在自己的复杂图分析场景中快速搭建出直观、可交互的局部关系洞察能力。

登录后查看全文
G6