模块 1 -- 项目概述与架构总览

理解 @antv/g 的定位、设计理念、整体架构与核心技术栈

1. @antv/g 是什么

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

• Canvas2D传统 2D 位图渲染
• SVG矢量图形渲染
• WebGLGPU 加速 2D/3D
• WebGPU下一代 GPU API
• CanvasKit基于 Skia 的高质量渲染
• Node.js服务端渲染（SSR）

项目源自蚂蚁集团 AntV 团队，采用 MIT 开源协议，GitHub 仓库位于 github.com/antvis/g。 当前核心包 @antv/g-lite 版本为 2.7.0，采用 pnpm + monorepo 管理。

2. 设计理念

2.1 DOM 兼容 API

G 的图形系统和事件系统与 DOM Element / Event API 兼容。 这意味着你可以像操作 DOM 一样操作场景中的图形节点：

• 节点操作：appendChild、removeChild、querySelector、getElementById
• 属性操作：getAttribute、setAttribute、style 代理
• 事件系统：addEventListener、dispatchEvent，支持冒泡和捕获
• CSS 选择器查询：querySelector('.myClass')、querySelectorAll('[name="foo"]')

这种设计使得 G 可以极低成本适配 Web 侧现有生态：D3.js 可以直接操作 G 的场景图， Hammer.js 手势库可以直接绑定事件。

2.2 Web 标准动画

动画系统兼容 Web Animations API (WAAPI)。 DisplayObject 提供 animate() 方法，返回 Animation 对象， 支持 play()、pause()、cancel()、finish() 等标准控制。 Document 维护全局 timeline，用于时间同步和群组动画。

2.3 多后端渲染

通过渲染器抽象层，G 将渲染后端解耦。运行时可以切换渲染器：

import { Canvas, Circle, CanvasEvent } from '@antv/g';
import { Renderer as CanvasRenderer } from '@antv/g-canvas';
// 切换渲染器只需更换 import
// import { Renderer as SVGRenderer } from '@antv/g-svg';
// import { Renderer as WebGLRenderer } from '@antv/g-webgl';

const canvas = new Canvas({
    container: 'container',
    width: 500,
    height: 500,
    renderer: new CanvasRenderer(),
});

const circle = new Circle({
    style: {
        cx: 100,
        cy: 100,
        r: 50,
        fill: 'red',
        stroke: 'blue',
        lineWidth: 5,
    },
});

canvas.addEventListener(CanvasEvent.READY, function () {
    canvas.appendChild(circle);
});

2.4 插件化架构

G 采用可扩展的插件机制，将渲染、拾取（Picking）、交互、物理引擎、布局引擎、 GPGPU 计算等能力都封装为独立插件。渲染器内部也由多个插件组合而成，用户可按需裁剪。

3. 整体架构图

+------------------------------------------------------------------+
|                        上层产品 (Consumers)                       |
|     G2 (图表)   G6 (图分析)   S2 (表格)   L7 (地理)   ...        |
+-------------------------------+----------------------------------+
                                |
+-------------------------------v----------------------------------+
|                    @antv/g  (扩展入口包)                          |
|          re-exports g-lite + g-plugin-css-select 等               |
+-------------------------------+----------------------------------+
                                |
+-------------------------------v----------------------------------+
|                      @antv/g-lite  (核心)                         |
|                                                                   |
|   +--------------+  +------------+  +---------------------+      |
|   |  场景图       |  |  事件系统   |  |  动画系统 (WAAPI)    |      |
|   |  Scene Graph  |  |  Events    |  |  Animations         |      |
|   +--------------+  +------------+  +---------------------+      |
|   +--------------+  +------------+  +---------------------+      |
|   |  DOM 兼容层   |  |  CSS 属性   |  |  渲染服务抽象        |      |
|   |  Element/Node |  |  Parsing   |  |  RenderingService   |      |
|   +--------------+  +------------+  +---------------------+      |
+-------------------------------+----------------------------------+
                                |
+-------------------------------v----------------------------------+
|                      渲染器 (Renderers)                           |
|                                                                   |
|   g-canvas       g-svg       g-webgl      g-webgpu               |
|   (Canvas2D)     (SVG DOM)   (WebGL)      (WebGPU)               |
|                                                                   |
|   g-canvaskit    g-mobile-canvas / g-mobile-svg / g-mobile-webgl  |
|   (Skia)         (移动端适配)                                     |
+-------------------------------+----------------------------------+
                                |
+-------------------------------v----------------------------------+
|                       插件 (Plugins)                              |
|                                                                   |
|  渲染: canvas-renderer, svg-renderer, device-renderer,          |
|       rough-canvas-renderer, rough-svg-renderer, canvaskit        |
|  拾取: canvas-picker, svg-picker                                |
|  交互: dom-interaction, control, dragndrop, gesture              |
|  物理: box2d, matterjs, physx                                   |
|  布局: yoga (Flex)                                                |
|  计算: gpgpu (WebGPU GPGPU)                                      |
|  其他: css-select, a11y, annotation, 3d                           |
+------------------------------------------------------------------+

4. 包结构总览

G 采用 pnpm + monorepo 管理，所有包位于 packages/ 目录下。 按职责可分为以下几类：

4.1 核心包

4.2 渲染器包

4.3 插件包（g-plugin-*）

4.4 其他包

5. 核心技术栈

5.1 TypeScript

整个项目使用 TypeScript 编写，大量运用泛型确保类型安全。例如 DisplayObject 的定义：

export class DisplayObject<
    StyleProps extends BaseStyleProps = any,
    ParsedStyleProps extends ParsedBaseStyleProps = any,
> extends Element<StyleProps, ParsedStyleProps> {
    // ...
}

每个图形类（Circle、Rect、Path 等）都有独立的 StyleProps 类型定义，编辑器可以提供完整的属性补全。

5.2 gl-matrix

使用 gl-matrix 进行所有矩阵和向量运算。 在 DisplayObject.ts 头部可以看到：

import type { mat3, vec2 } from 'gl-matrix';
import { mat4, quat, vec3 } from 'gl-matrix';

mat4 用于表示 4x4 世界变换矩阵（支持 3D），quat 用于四元数旋转表示， vec3 用于三维坐标。变换分解函数 decompose、fromRotationTranslationScale 等封装在 utils 中。

5.3 monorepo 工具链

• pnpm workspaces -- 包管理和依赖复用
• Vite -- 开发服务器和 demo 预览
• Jest -- 单元测试和视觉回归测试
• ESLint -- 代码质量检查
• semantic-release (Angular) -- 语义化版本发布

5.4 运行时架构

G 通过 runtime 全局对象（位于 g-lite/src/global-runtime.ts）管理运行时依赖注入。 这使得核心代码不依赖任何具体渲染实现：

// 运行时服务注册示例
runtime.sceneGraphService    // 场景图服务（节点挂载、查询）
runtime.styleValueRegistry    // CSS 属性解析注册表
runtime.CameraContribution    // 相机实现
runtime.AnimationTimeline     // 动画时间线实现
runtime.enableStyleSyntax     // 是否启用 style 代理
runtime.globalThis           // 跨环境全局对象

6. 与同类库对比

7. 快速上手

7.1 安装

# 安装核心包（包含 g-lite + 常用插件）
npm install @antv/g --save

# 选择一个渲染器
npm install @antv/g-canvas --save     # Canvas2D
npm install @antv/g-svg --save        # SVG
npm install @antv/g-webgl --save      # WebGL

7.2 Hello World

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

// 1. 创建画布，选择渲染器
const canvas = new Canvas({
    container: 'container',  // DOM 容器 id
    width: 500,
    height: 500,
    renderer: new CanvasRenderer(),
});

// 2. 创建图形
const circle = new Circle({
    style: {
        cx: 100,
        cy: 100,
        r: 50,
        fill: '#1890ff',
        stroke: '#fff',
        lineWidth: 2,
        cursor: 'pointer',
    },
});

// 3. 等待画布就绪后挂载
canvas.addEventListener(CanvasEvent.READY, () => {
    canvas.appendChild(circle);

    // 4. 绑定事件 -- 与 DOM 完全一致
    circle.addEventListener('click', () => {
        // 5. 播放动画 -- Web Animations API
        circle.animate(
            [
                { transform: 'scale(1)', fill: '#1890ff' },
                { transform: 'scale(1.5)', fill: '#f5222d' },
                { transform: 'scale(1)', fill: '#1890ff' },
            ],
            { duration: 600, easing: 'ease-in-out' },
        );
    });
});

7.3 Canvas 事件生命周期

Canvas 类定义了以下事件（源自 Canvas.ts）：

export enum CanvasEvent {
    READY           = 'ready',          // 画布初始化完成
    BEFORE_RENDER   = 'beforerender',   // 每帧渲染前
    RERENDER        = 'rerender',       // 重渲染触发
    AFTER_RENDER    = 'afterrender',    // 每帧渲染后
    BEFORE_DESTROY  = 'beforedestroy',  // 销毁前
    AFTER_DESTROY   = 'afterdestroy',   // 销毁后
    RESIZE          = 'resize',         // 画布尺寸变化
    DIRTY_RECTANGLE = 'dirtyrectangle', // 脏矩形更新
    RENDERER_CHANGED= 'rendererchanged',// 渲染器切换
}