Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@antv/g-math

antvis956.5kMIT3.0.1TypeScript support: included

Geometry util

antv, g

readme

g-math

为 G 提供几何图形运算的库

安装下载

tnpm i --save @antv/g-math

// 所有的 api 是都这么引入，名字不同而已
import { line } from '@antv/g-math';

const len = line.length(x1, x2, x2, y2);

API 文档

目前使用到的、且推荐使用的 API 文档，不在文档内的不建议使用。

changelog

Change Log

以下版本号以 @antv/g 为准。

[5.0.17] - 2022-3-22

Bug 修复

  • [g] keyframe 动画 delay 属性问题 #919

其他

[5.0.16] - 2022-3-20

新增特性

  • [g] 支持使用 MutationObserver 监听属性变更，文档
  • [g] 部分属性支持继承，例如 fontSize #895
  • [g] width / height / lineWidth / fontSize 支持使用单位，类型支持 number | string #895
  • [g] Polygon / Polyline / Path 支持 miterLimit 属性
  • [g] 考虑 D3 等基于 SVG 项目的兼容，支持属性名的连字符写法，例如 font-size，效果等同驼峰写法。同时增加以下属性作为已由属性的别名 stroke-width stroke-dasharray
  • [g] Image 支持 src 属性 #814
  • [g-mobile] 移动端渲染器，和 g-canvas 共用部分 Canvas2D 插件 g-plugin-canvas-renderer g-plugin-canvas-picker #910
  • [g-plugin-mobile-interaction] 移动端监听事件并触发 G 原生事件
  • [g-webgl] 支持 PointMaterial
  • [g-devtools] 开发者工具 Chrome 插件 #911

Bug 修复

  • [g] 移动端不会触发 tap 事件，使用 click 事件代替
  • [g] 为 2D 图形提供更快的剔除 #914 #908
  • [g-svg] 初始渲染次序问题

Bug 修复

[5.0.15] - 2022-3-8

新增特性

[5.0.14] - 2022-3-4

新增特性

Bug 修复

  • [g-webgl] WebGL2 首屏渲染白屏

[5.0.13] - 2022-2-28

Bug 修复

[5.0.12] - 2022-2-27

新增特性

  • [g] 支持通过 displayObject.getRotation() 等方式获取/设置旋转四元数
  • [g] 支持创建画布时通过 requestAnimationFrame/cancelAnimationFrame 设置自定义函数，适用于非浏览器环境
  • [g-plugin-box2d] 支持 Box2D 物理引擎

[5.0.11] - 2022-2-22

新增特性

  • [g] 支持 OffscreenCanvas，现在 g 和 g-webgl 均可以在 WebWorker 中运行 https://github.com/antvis/g/issues/874
  • [g] 创建 Canvas 支持传入 canvas，如果传入 G 不会再自动创建 <canvas>，因此 container 不再是必填项。当用户想使用已有 <canvas> 或在 WebWorker 中使用 OffscreenCanvas，现在 时适用
  • [g] 创建 Canvas 支持传入 devicePixelRatio
  • [g-webgl] 重构了自动合并 mesh 逻辑
  • [g-plugin-gpgpu] Kernel 第一个参数为 device，和其他 GPU 对象例如 Geometry / Material 保持风格一致

Bug 修复

其他

[5.0.10] - 2022-2-7

Bug 修复

  • [g-webgl] 修改了 BufferGeometry 的用法，需要使用 Device 创建

其他

[5.0.10] - 2022-2-5

新增特性

Bug 修复

[5.0.9] - 2022-1-24

Bug 修复

  • [g-webgl] 硬件适配层支持 WebGL1 #851
  • [g-webgl] Polygon Path 描边闭合 #860
  • [g-webgl] 渲染次序问题 #859

[5.0.8] - 2022-1-18

无新增特性。重命名 dist/index.umd.js -> dist/index.umd.min.js

Bug 修复

修复 g-plugin-3d UMD 打包问题。

[5.0.7] - 2022-1-17

新增特性

Bug 修复

[1.0.0-alpha.37] - 2021-12-02

Bug 修复

[1.0.0-alpha.27] - 2021-11-08

Bug 修复

[1.0.0-alpha.26] - 2021-11-08

新增特性

使用 mana-syringe 替换 inversify。

[1.0.0-alpha.24] - 2021-11-04

新增特性

  • [g-webgl] 支持 WebGL2。详见引擎设计。
  • [g-webgl] 使用 instanced 渲染 Line、Text、Circle、Ellipse 大幅提升渲染性能。详见性能优化。

Bug 修复

  • [g] 考虑到包体积以及不适合浏览器环境，去除对 tapable 的依赖，使用 async-emitter 替代。

其他已知问题

  • [g-canvas] 频繁修改属性导致重绘性能问题
  • [g-webgl] 自动降级成 WebGL1，支持 WebGPU。

[1.0.0-alpha.23] - 2021-09-27

Bug 修复

  • [path-util] 转换无效 A 命令出错，例如 GUI 中使用的：

    [['A', 0, 0, 0, 0, 0, 0, 0]];

[1.0.0-alpha.22] - 2021-09-26

Bug 修复

  • [g] Canvas 传入参数 Renderer 类型报错
  • [g-plugin-control] 使用 hammer.js 监听手势事件，使用 Passive Event Listener 处理 wheel 事件

[1.0.0-alpha.21] - 2021-09-25

新增特性

  • 明确了 G 目前使用到的坐标系，提供各个坐标系间的转换方法：Client <-> Viewport <-> Canvas

    • client2Viewport(client: Point): Point
    • viewport2Client(canvas: Point): Point
    • viewport2Canvas(viewport: Point): Point
    • canvas2Viewport(canvas: Point): Point

  • 支持节点克隆，cloneNode(deep?: boolean) 在任何时刻都可以进行图形的克隆，例如：

    circle.style.r = 20;
circle.setPosition(10, 20);

const clonedCircle = circle.cloneNode();
clonedCircle.style.r; // 20
clonedCircle.getPosition(); // [10, 20]

    注意事项：

    • 支持深拷贝，即自身以及整棵子树
    • 克隆的新节点不会保留原始节点的父子关系，需要使用 appendChild 将其加入画布才会被渲染
    • 与 DOM API 保持一致，不会拷贝原图形上的事件监听器。

  • 支持使用 document.createElement() 创建图形，作为 new Circle() 的另一种选择，类似旧版 G 的 addShape()：

    import { Shape, Circle } from '@antv/g';

const circle = canvas.document.createElement(Shape.CIRCLE, { style: { r: 100 } });
// 或者
const circle = new Circle({ style: { r: 100 } });

    除了内置图形，自定义图形如果也想用这种方式创建，需要先注册：

    import { MyCustomShape } from 'my-custom-shape';
canvas.customElements.define(MyCustomShape.tag, MyCustomShape);

const myCustomShape = canvas.document.createElement(MyCustomShape.tag, {});

  • 补全 ComputedEffectTiming

    • endTime
    • activeDuration
    • localTime
    • progress
    • currentIteration

  • updateTiming

  • resetLocalTransform 重置局部坐标系下的变换 https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/resetTransform

    circle.resetLocalTransform();

// 等价于
circle.setLocalScale(1);
circle.setLocalPosition(0, 0);
circle.setLocalEulerAngles(0);

改动

  • 重构 DisplayObject，在原有的继承链（DisplayObject -> Element -> Node -> EventTarget）基础上，将动画、变换等能力拆解成多个 mixin：
    • Animatable
    • Transformable
    • Visible
  • 包围盒 API，区分了 Bounds，LocalBounds，GeometryBounds 以及 RenderBounds 这四种包围盒：
    • getBounds 世界坐标系下的包围盒
    • getLocalBounds 在父元素局部空间下的包围盒
    • getGeometryBounds 不考虑所有子元素，例如：
      const geometryBounds = circle.getGeometryBounds();
circle.appendChild(child1); // 添加一堆子元素
circle.appendChild(child2);
circle.appendChild(child3);
circle.getGeometryBounds(); // 尺寸依然等于 geometryBounds
    • getRenderBounds 会考虑一些绘图属性，例如 lineWidth 边框宽度，padding，阴影以及部分滤镜（blur、drop-shadow），顾名思义它在渲染管线中会使用到：
      • 脏矩形渲染中清除区域据此计算
      • 内置剔除插件使用该包围盒

Bug 修复

  • [g] querySelectorAll 无法按 id 查询问题
  • [g] 无法获取 style.origin，无法设置 Group 的 origin
  • [g] 设置 transformOrigin 无效
  • [g] addEventListener 设置 once 无效
  • [g-canvas]设置阴影 shadowBlur 影响不应影响子元素
  • [path-util] 直线转三次贝塞尔曲线有误，导致 getPoint() 无法获取正确点坐标 https://github.com/antvis/util/issues/68
  • [g-canvas] 相机发生变换后，g-canvas 拾取无效

[1.0.0-alpha.20] - 2021-09-13

新增特性

改动

  • 构建 esm/cjs 选择 babel 模式，之前为 rollup，构建产物文件结构有较大变化。
  • 拾取逻辑。点击画布空白处时，事件对象 target 为 Document。
  • 参考 DOM API 重构了内部继承关系：
    • Canvas -> EventTarget
    • Document -> Node -> EventTarget
    • DisplayObject -> Element -> Node -> EventTarget

  • Canvas 提供获取入口和场景图根节点方法：https://g-next.antv.vision/zh/docs/api/canvas#%E5%85%A5%E5%8F%A3%E4%B8%8E%E6%A0%B9%E8%8A%82%E7%82%B9

    canvas.document; // 入口
canvas.document.documentElement; // 场景图根节点
// 或者
canvas.getRoot(); // 场景图根节点

// 向场景图根节点中添加节点
canvas.appendChild(circle);
// 或者
canvas.document.documentElement.appendChild(circle);

Bug 修复

  • g-svg 渲染节点时丢失变换矩阵问题。该问题是由删除节点之后排序时未及时更新导致。
  • g-canvas 残影问题 https://codesandbox.io/s/exciting-pike-z7lt8?file=/index.js 在设置 z 坐标大于 500 时出现。目前内置的默认正交相机在世界坐标系位置为 [width / 2, height / 2, 500]，视点为 [width / 2, height / 2, 0]。因此 z > 500 代表图形出现在了相机之后，内置的剔除插件会将其剔除，因此正确的展示效果为该图形不可见。

其他已知问题

  • Node.cloneNode 待实现，可进行图形的复制。
  • 视口坐标系与世界坐标系、Client 坐标系的转换方法。
  • HTML 图形事件响应有问题。
  • 文本阴影待实现。
  • path-util 转曲遗留问题：https://github.com/antvis/util/issues/68
  • g-webgl Line/Path/Polygon/Polyline 待实现。
  • father 选用 babel 编译 cjs 时在 @antv/g-plugin-device-renderer 中报错