G6 网格线插件（GridLine）完全指南：画布对齐辅助线的配置、跟随模式与实现原理

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

GridLine 是 G6 内置的画布辅助线插件，通过绘制可定制的网格背景，帮助用户在绘图过程中精准定位与对齐图形元素，是搭建"类设计器"式图编辑体验的常用基础设施。本文以 GridLine 官方文档 为核心骨架，结合 grid-line.ts 源码 与运行时事件机制，系统讲解其全部配置项、跟随画布移动的两种模式、运行时动态更新技巧，以及背后的 DOM + CSS 实现原理，读完即可在项目中快速落地并二次定制。

概述：网格线在 G6 中的定位

网格线插件（type: 'grid-line'）为画布提供视觉辅助线系统，它的核心价值体现在三方面：

• 辅助精确绘图：用户拖拽、放置节点时，网格提供了可参照的坐标标尺；
• 提供视觉参照：网格强化用户对画布空间与元素间距的感知，降低误操作概率；
• 构建结构化参照系：在设计、编辑类图应用（如流程图编辑器、画板工具）中，网格是"栅格化对齐"体验的基础设施。

从实现方式上看，它并不参与 G6 自身的场景渲染（场景由@antv/g渲染到 canvas），而是作为一个覆盖在画布之上的 DOM 层独立绘制网格，因此它的渲染成本与图元数量无关，即使面对上万节点的图，网格本身依然轻量。

快速开始：最简单的接入方式

将grid-line作为字符串直接放入plugins数组即可启用全部默认配置：

const graph = new Graph({ // Other configurations... plugins: ['grid-line'], });

也可以传入对象形式，并显式指定插件标识与样式：

const graph = new Graph({ plugins: [ { type: 'grid-line', key: 'my-grid-line', // 唯一标识，用于动态更新或获取实例 size: 20, stroke: '#0001', follow: true, }, ], });

一个可运行的最小示例（渲染单个节点并开启画布拖拽）：

import { Graph } from '@antv/g6'; const graph = new Graph({ container: 'container', width: 300, height: 150, data: { nodes: [{ id: 'node-1', style: { x: 150, y: 75 } }] }, behaviors: ['drag-canvas'], plugins: ['grid-line'], }); graph.render();

type: 'grid-line'是 G6 内置注册的插件类型，可在 build-in.ts 内置扩展注册表 中找到'grid-line': GridLine的映射，并在 插件统一导出入口 中确认GridLine类的导出，因此无需额外引入即可使用。

配置选项全解

下表完整列出了 GridLine 插件的全部配置项（与官方文档一致）：

这些默认值可以在 GridLine.defaultOptions 中逐一验证：border: true、borderLineWidth: 1、borderStroke: '#eee'、borderStyle: 'solid'、lineWidth: 1、size: 20、stroke: '#eee'。而follow在 GridLineOptions 接口注释 中标注默认值为false。

各参数的作用与取值建议

• size（网格单元尺寸）：控制相邻网格线的间距，单位像素。数值越小网格越密。适合需要精细对齐的编辑场景设置 10~20，需要宽松视觉参考时设置为 40 或更大。
• stroke/lineWidth（网格线颜色与线宽）：stroke支持任意合法的 CSS 颜色值（含透明度），如'#1890ff33'这种带 alpha 通道的半透明写法；lineWidth类型为number | string，既可以直接给数值，也可以给出'1px'这类字符串。
• border系列（画布外框）：border控制是否绘制画布边界框；borderLineWidth、borderStroke、borderStyle分别对应边框的宽度、颜色与样式（solid、dashed、dotted等 CSS 取值）。边框有助于把"画布范围"从页面背景中清晰地区分出来。
• key（唯一标识）：当需要运行期通过graph.updatePlugin更新网格配置，或通过graph.getPluginInstance拿到插件实例时，必须为插件指定唯一的key。
• follow（跟随模式）：控制网格是否随画布平移/缩放联动，支持布尔值与对象两种形态，详见下一节。

follow：网格如何跟随画布变换

follow属性决定网格线是否跟随画布的视口变换（平移与缩放），支持两种配置方式：

1. 布尔配置：一键开启整体跟随

当设置为true时，网格同时跟随画布的平移与缩放；设置为false时网格静止在画布背景中：

// 同时开启平移与缩放跟随 const graph = new Graph({ plugins: [ { type: 'grid-line', follow: true, }, ], });

从源码看，布尔值会被 parseFollow 归一化为{ translate: follow, zoom: follow }，即布尔true等价于同时开启平移与缩放跟随。

2. 对象配置：平移与缩放分开控制

当需要更精细的控制时，使用对象形式分别指定translate与zoom：

// 只跟随平移，不跟随缩放 const graph = new Graph({ plugins: [ { type: 'grid-line', follow: { translate: true, // 跟随平移 zoom: false, // 不跟随缩放 }, }, ], }); // 只跟随缩放，不跟随平移 const graph = new Graph({ plugins: [ { type: 'grid-line', follow: { translate: false, // 不跟随平移 zoom: true, // 跟随缩放 }, }, ], });

两种跟随的体验差异

• 跟随缩放（zoom: true）：网格单元尺寸会随画布缩放等比变化（网格线相对画布内容保持位置关系），使对齐参照在任意缩放级别下都保持"相对内容"的精度；
• 跟随平移（translate: true）：网格随画布内容一起移动，营造空间连续感，避免拖拽画布后网格与内容"脱节"。

实际项目中常见组合是"跟随缩放但静止平移"（保持网格作为全局坐标系）、"两者都跟随"（完全贴合内容）以及"两者都不跟随"（网格作为固定页面背景）。

完整代码示例

自定义网格样式

按照业务视觉规范定制网格线颜色、粗细、单元大小与边框样式：

const graph = new Graph({ // Other configurations... plugins: [ { type: 'grid-line', stroke: '#1890ff33', // 蓝色半透明网格线 lineWidth: 2, size: 40, // 更大的网格单元 borderStroke: '#1890ff', // 蓝色边框 borderLineWidth: 2, }, ], });

运行效果：

import { Graph } from '@antv/g6'; const graph = new Graph({ container: 'container', width: 300, height: 150, data: { nodes: [{ id: 'node-1', style: { x: 150, y: 75 } }] }, behaviors: ['drag-canvas'], plugins: [ { type: 'grid-line', stroke: '#1890ff33', // 蓝色半透明网格线 lineWidth: 2, size: 40, // 更大的网格单元 borderStroke: '#1890ff', // 蓝色边框 borderLineWidth: 2, }, ], }); graph.render();

网格跟随画布移动

配合drag-canvas与zoom-canvas行为，开启整体跟随：

const graph = new Graph({ // Other configurations... behaviors: ['drag-canvas', 'zoom-canvas'], plugins: [ { type: 'grid-line', follow: true, // 网格跟随画布移动 }, ], });

拖拽或缩放画布即可观察网格的跟随效果：

import { Graph } from '@antv/g6'; const graph = new Graph({ container: 'container', width: 300, height: 150, data: { nodes: [{ id: 'node-1', style: { x: 150, y: 75 } }] }, behaviors: ['drag-canvas', 'zoom-canvas'], plugins: [ { type: 'grid-line', follow: true, // 网格跟随画布移动 }, ], }); graph.render();

运行期动态更新网格

利用key标识 +graph.updatePlugin，在运行时切换网格尺寸、颜色等配置，无需重建图实例：

// 初始配置 const graph = new Graph({ // Other configurations... plugins: [ { type: 'grid-line', key: 'my-grid', size: 20, }, ], }); // 运行期动态更新 graph.updatePlugin({ key: 'my-grid', size: 40, // 更新网格尺寸 stroke: '#ff4d4f', // 更新网格颜色 });

updatePlugin的语义可在 graph.ts 的 updatePlugin 实现 中看到：它按key匹配插件配置并做浅合并后重新设置插件集，最终由 PluginController.setPlugins 完成增量更新。对应地，GridLine的 update 方法 会同步刷新baseSize并重算样式，因此size等参数的改动会即时生效。

实战案例：网格 + 布局 + 控制面板联动

以下案例将网格线、grid布局与 gui 控制面板组合：通过面板开关follow，实时观察网格在"静止"与"跟随"之间的切换效果：

import { Graph } from '@antv/g6'; const data = { nodes: [{ id: 'node-0' }, { id: 'node-1' }, { id: 'node-2' }, { id: 'node-3' }, { id: 'node-4' }, { id: 'node-5' }], edges: [ { source: 'node-0', target: 'node-1' }, { source: 'node-0', target: 'node-2' }, { source: 'node-0', target: 'node-3' }, { source: 'node-0', target: 'node-4' }, { source: 'node-1', target: 'node-0' }, { source: 'node-2', target: 'node-0' }, { source: 'node-3', target: 'node-0' }, { source: 'node-4', target: 'node-0' }, { source: 'node-5', target: 'node-0' }, ], }; const graph = new Graph({ container: 'container', data, layout: { type: 'grid' }, behaviors: ['drag-canvas'], plugins: [{ key: 'grid-line', type: 'grid-line', follow: false }], }); graph.render(); window.addPanel((gui) => { gui .add({ follow: false }, 'follow') .name('Follow') .onChange((value) => { graph.updatePlugin({ key: 'grid-line', follow: value, }); }); });

这个案例展示了三个实战要点：其一，follow可以在运行期通过updatePlugin平滑切换；其二，key必须与初始配置保持一致才能命中更新目标；其三，网格线可与布局算法（此处为grid布局）协同，形成"网格 + 栅格化排列"的一致视觉语言。

源码解读：网格线是如何画出来的

GridLine 的渲染不依赖 canvas 绘制指令，而是纯 DOM + CSS 实现，理解这一点有助于你按需定制。

覆盖层容器

构造时，插件通过 createPluginContainer('grid-line', true) 创建一个覆盖整个画布的div，并挂载到 canvas 容器的最前面（prepend）。该容器具备以下关键样式：

• gridArea: '1 / 1 / 2 / 2'、inset: 0：与画布容器等尺寸叠加；
• overflow: hidden：网格绘制超出画布区域时自动裁剪；
• pointerEvents: 'none'：不拦截任何鼠标事件，网格层下方的拖拽、缩放等行为不受影响。

这也是网格与内容"分层"的关键：网格永远位于场景之上（可见），但交互上完全透明。

网格线的 CSS 绘制

updateStyle 方法 用两条互相垂直的渐变背景叠加出网格线：

background-image: linear-gradient(stroke lineWidth, transparent lineWidth), linear-gradient(90deg, stroke lineWidth, transparent lineWidth); background-size: scaledSize scaledSize; background-repeat: repeat;

• 第一条linear-gradient产生水平方向网格线，第二条旋转 90° 产生垂直方向网格线，两者叠加即形成网格；
• background-size由baseSize * currentScale计算得出——这正是缩放跟随的载体；
• 边框则由border: ${borderLineWidth}px ${borderStyle} ${borderStroke}直接设置，border: false时置为none。

变换跟随的事件链路

GridLine 通过监听视口变换事件实现跟随：

1. 视口发生平移/缩放时，viewport.ts 的 transform 方法 在变换完成后派发GraphEvent.AFTER_TRANSFORM事件（事件名aftertransform，定义于 graph 事件常量）；
2. 事件载荷是 ViewportEvent，携带translate、scale、origin等变换数据；
3. bindEvents 中graph.on(GraphEvent.AFTER_TRANSFORM, this.onTransform)完成监听，onTransform 依据follow解析结果分派到followZoom/followTranslate。

平移跟随（followTranslate）的核心是把事件携带的位移增量累加到backgroundPosition，并通过mod取模运算让偏移量始终落在单个网格单元范围内，避免数值无限累积。

缩放跟随（followZoom）的核心是一个保持"锚点不动"的坐标换算：计算缩放前后比例deltaScale，以缩放原点origin（无缩放原点时退化为画布中心）为不动点，将网格偏移量按1 - deltaScale反推平移补偿，同时把backgroundSize更新为baseSize * scale，从而让网格在缩放过程中始终"钉住"画布上的同一点。这也是"跟随缩放时网格保持相对内容位置"的数学来源。

生命周期

• 销毁：destroy 方法 会解绑AFTER_TRANSFORM监听并移除 DOM 容器，避免内存泄漏与残留；
• 类型安全：GridLineOptions接口（grid-line.ts 顶部）对所有配置项提供了完整的 TypeScript 类型标注与默认值说明，配合GridLineOptions类型导出（插件类型导出）可获得 IDE 智能提示。

相关参考

• 插件官方文档（英文版）：GridLine.en.md，中文版见 GridLine.zh.md；
• 插件 API 速查：plugins/grid-line.md；
• 插件源码：packages/g6/src/plugins/grid-line.ts；
• 插件基类与容器工具：base-plugin.ts、dom.ts；
• 内置注册表：packages/g6/src/registry/build-in.ts；
• 视口变换与插件运行时：runtime/viewport.ts、runtime/plugin.ts；
• 演示与测试：GridLine 相关的可视化 demo 见 packages/g6/tests/demos/plugin-grid-line.ts，单元测试见 packages/g6/tests/unit/plugins/grid-line.spec.ts。

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