项目概述与架构总览

◆@antv/g 是什么

@antv/g 是蚂蚁集团 AntV 可视化技术栈的底层渲染引擎。它为上层产品（如 G2、G6、S2、L7 等）提供一致且高性能的 2D / 3D 图形渲染能力，能够适配 Web 端所有底层渲染 API：

快速上手示例

以下代码展示了 G 的基本用法 -- 创建画布、添加图形、绑定事件：

// 1. 安装依赖
// npm install @antv/g @antv/g-canvas

import { Circle, Canvas, CanvasEvent } from '@antv/g';
import { Renderer as CanvasRenderer } from '@antv/g-canvas';

// 2. 创建画布，指定渲染器
const canvas = new Canvas({
  container: 'container',
  width: 500,
  height: 500,
  renderer: new CanvasRenderer(),
});

// 3. 创建图形（API 兼容 DOM Element）
const circle = new Circle({
  style: {
    cx: 100,
    cy: 100,
    r: 50,
    fill: '#1890ff',
    stroke: '#0050b3',
    lineWidth: 3,
  },
});

// 4. 画布就绪后添加图形
canvas.addEventListener(CanvasEvent.READY, () => {
  canvas.appendChild(circle);  // 等同 DOM 的 appendChild

  // 5. 绑定事件（API 兼容 DOM Event）
  circle.addEventListener('click', () => {
    circle.style.fill = '#52c41a';
  });
});TypeScript

★设计理念

1. DOM 兼容 API

G 的图形和事件系统兼容 DOM Element 和 Event API。每个图形对象（如 Circle、Rect）都像一个 DOM 节点，支持 appendChild、removeChild、querySelector 等方法。事件系统兼容 addEventListener，支持冒泡、捕获、阻止传播等完整的事件流。

这意味着 Web 生态中大量依赖 DOM API 的库可以几乎零成本接入 G，例如：

• D3.js -- 数据驱动的可视化库，可直接操作 G 的场景图
• Hammer.js -- 手势识别库，可直接绑定到 G 的图形对象
• interact.js -- 拖拽交互库

2. Web Animations API 兼容

动画系统兼容 Web Animations API，使用 element.animate() 来创建动画，支持关键帧、缓动函数、播放控制等：

// 和浏览器原生 Web Animations API 一致
circle.animate(
  [
    { transform: 'scale(1)', fill: '#1890ff' },
    { transform: 'scale(1.5)', fill: '#f5222d' },
  ],
  {
    duration: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
  }
);TypeScript

3. 渲染后端无关

核心 API 层与渲染实现完全解耦。通过切换渲染器，同一套业务代码可以运行在 Canvas2D、SVG、WebGL、WebGPU 等不同环境中，无需修改任何逻辑：

import { Renderer as CanvasRenderer } from '@antv/g-canvas';
import { Renderer as SVGRenderer } from '@antv/g-svg';
import { Renderer as WebGLRenderer } from '@antv/g-webgl';

// 只需更换渲染器，其他代码完全不变
const canvas = new Canvas({
  container: 'container',
  width: 600,
  height: 400,
  renderer: new CanvasRenderer(),  // 换成 SVGRenderer() 或 WebGLRenderer() 即可
});TypeScript

4. 插件化架构

G 采用高度插件化的架构，渲染器本身就是一组插件的集合。用户可以按需引入拾取、交互、物理引擎、布局引擎等插件，避免不必要的包体积膨胀。

◫整体架构图

下图展示了 G 的分层架构，从上层应用到底层渲染 API 的完整链路：

架构分层说明

☰包结构总览

G 采用 Monorepo 架构（基于 pnpm workspace），所有包位于 packages/ 目录下。截至当前版本共有 32 个子包，可分为以下几类：

核心包

渲染器包

插件包

工具与扩展包

☍核心包 vs 渲染器 vs 插件的关系

理解三者之间的依赖关系是掌握 G 架构的关键。以下用依赖流方向来说明：

// 依赖关系（箭头表示 "依赖于"）

// 核心链路：
@antv/g  ─────── 依赖 ──▶  @antv/g-lite  ─── 依赖 ──▶  @antv/g-math

// 渲染器 依赖 核心：
@antv/g-canvas  ─── 依赖 ──▶  @antv/g-lite + @antv/g-math
@antv/g-svg     ─── 依赖 ──▶  @antv/g-lite
@antv/g-webgl   ─── 依赖 ──▶  @antv/g-lite + g-plugin-device-renderer
@antv/g-webgpu  ─── 依赖 ──▶  @antv/g-lite + g-plugin-device-renderer

// 插件 依赖 核心（不依赖具体渲染器）：
g-plugin-3d         ─── 依赖 ──▶  @antv/g-lite + g-plugin-device-renderer
g-plugin-dragndrop  ─── 依赖 ──▶  @antv/g-lite
g-plugin-control    ─── 依赖 ──▶  @antv/g-lite依赖关系

关键设计原则

渲染器的插件组成

以 @antv/g-canvas 为例，它实际上注册了以下内置插件：

// g-canvas 渲染器内部组成（简化示意）
class Renderer extends AbstractRenderer {
  constructor() {
    super();
    // 内置插件集
    this.registerPlugin(new CanvasRendererPlugin());   // 渲染
    this.registerPlugin(new CanvasPickerPlugin());     // 拾取（点击检测）
    this.registerPlugin(new DOMInteractionPlugin());   // DOM 事件绑定
    this.registerPlugin(new HTMLRendererPlugin());     // HTML 元素渲染
  }
}

// 用户可以额外注册插件
const renderer = new Renderer();
renderer.registerPlugin(new DragndropPlugin());  // 添加拖拽能力
renderer.registerPlugin(new A11yPlugin());       // 添加无障碍支持TypeScript

⚙技术栈

g-lite 核心源码结构

@antv/g-lite 是整个引擎的心脏，其源码按职责划分为以下模块：

packages/g-lite/src/
  ├── Canvas.ts              // 画布 - 顶层容器，管理渲染循环
  ├── AbstractRenderer.ts    // 渲染器抽象基类，定义插件注册机制
  ├── global-runtime.ts      // 全局运行时配置
  ├── camera/
  │   ├── Camera.ts          // 相机实现（正交/透视投影）
  │   └── Landmark.ts        // 相机地标（视角保存/恢复）
  ├── components/
  │   ├── Transform.ts       // 变换组件（位移/旋转/缩放矩阵）
  │   ├── Renderable.ts      // 可渲染组件（包围盒/脏标记）
  │   ├── Cullable.ts        // 裁剪组件（视锥剔除）
  │   ├── Sortable.ts        // 排序组件（渲染顺序/zIndex）
  │   └── Geometry.ts        // 几何组件
  ├── css/
  │   ├── CSS.ts             // CSS 属性解析引擎
  │   ├── StyleValueRegistry.ts // 样式值注册表
  │   ├── cssom/             // CSS 对象模型（颜色、渐变、关键字等）
  │   ├── parser/            // 属性值解析器（颜色/尺寸/变换/路径等）
  │   └── properties/        // 各 CSS 属性的处理器（18 个）
  ├── display-objects/
  │   ├── DisplayObject.ts   // 所有图形的基类
  │   ├── Circle.ts          // 圆
  │   ├── Ellipse.ts         // 椭圆
  │   ├── Rect.ts            // 矩形
  │   ├── Line.ts            // 线段
  │   ├── Path.ts            // 路径
  │   ├── Polygon.ts         // 多边形
  │   ├── Polyline.ts        // 折线
  │   ├── Text.ts            // 文本
  │   ├── Image.ts           // 图片
  │   ├── HTML.ts            // HTML 元素
  │   ├── Group.ts           // 分组容器
  │   └── CustomElement.ts   // 自定义元素
  ├── dom/
  │   ├── Node.ts            // DOM Node 接口实现
  │   ├── Element.ts         // DOM Element 接口实现
  │   ├── Document.ts        // DOM Document 接口实现
  │   ├── EventTarget.ts     // 事件目标基类
  │   ├── FederatedEvent.ts  // 联合事件（跨渲染器统一）
  │   ├── FederatedPointerEvent.ts // 指针事件
  │   ├── FederatedMouseEvent.ts   // 鼠标事件
  │   └── MutationObserver.ts      // DOM 变更观察器
  └── plugins/
      ├── EventPlugin.ts     // 事件处理插件
      ├── DirtyCheckPlugin.ts // 脏检查优化插件
      ├── CullingPlugin.ts   // 视锥剔除插件
      └── PrepareRendererPlugin.ts // 渲染准备插件目录结构

⚖与其他图形库的对比

为了更好地理解 G 的定位，我们将它与其他流行的 Web 图形库进行对比：

G 的最佳适用场景

• 企业级数据可视化 -- 图表引擎（G2）、图分析引擎（G6）等产品的底层
• 需要多渲染后端的场景 -- 同一套代码在桌面端用 Canvas、移动端用 WebGL、服务端渲染
• 与 D3 生态深度集成 -- 利用 DOM 兼容 API，直接复用 D3 的布局和数据处理能力
• 需要 2D + 3D 混合的可视化场景 -- 通过插件扩展 3D 能力
• 需要 GPU 加速计算的图分析场景 -- GPGPU 插件

✓本模块小结