G 的使用文档

快速上手

安装

推荐通过npm安装

npm i @antv/g

浏览器引入

<!-- 引入在线资源 -->
<script src="https://gw.alipayobjects.com/os/antv/pkg/_antv.g-3.2.2/dist/g-3.2.2.min.js"></script>

开发

$ git clone git@github.com:antvis/g.git
$ npm install
$ npm run dev

第一个demo

1. 创建div图标容器

在页面中需要添加画布的地方创建一个 div，并制定必须的属性 id：

<div id="c1"></div>

2. 创建画布

var canvas = new G.Canvas({
  containerId: 'c1',            // 指定画布容器
  width: 500,                    // 画布宽度
  height: 600                    // 画布高度
});

3. 给画布添加图形

// 定义一个以(100, 100)为中心，50为半径一个红色的圆
var circle = canvas.addShape('circle', {
    attrs: {
        x: 100,
        y: 100,
        r: 50,
        fill: 'red'
    }
});

详细形状属性可见下方Shape小节。

4. 绘制图形

canvas.draw()

画布 Canvas

所有图形的载体，可以看成是一种特殊的group。因此canvas提供了所有group的方法。详细可见group小节。

创建实例

const canvas = new Canvas(cfg);

• containerDOM: 容器DOM
• containerId：容器id
  
• width：指定画布宽度
  
• height：指定画布高度
  
• pixelRatio： 指定屏幕分辨率
  
• renderer：渲染模式，默认为canvas，可选择svg。
  

const canvas = new Canvas({
    containerId: 'containerId',
    width: 500,
    height: 500,
    pixelRatio: 2,
    renderer: 'canvas'
})

实例方法

• draw()
  

画布的绘制方法。新增shape或group后，调用此方法将最新的内容渲染到画布上。

• changeSize(width, height)
  

改变画布的大小。width为画布宽度，height为画布高度。

canvas.changeSize(500, 500);
canvas.draw();

• getClientByPoint(x, y)
  

将窗口坐标转换为canvas坐标。

• getPointByClient(x, y)
  

将canvas坐标转换为窗口坐标。

• on(eventType, callback)
  

绑定事件。
支持浏览器的常见事件：click|| dblclick| mouseenter| mouseleave| mouseover| mouseup| mousedown| mousemove| touchstart| touchend。

canvas.on('click', function(evt) {
    e.target.attr('cursor', 'crosshair');
});

• off(eventType, callback)
  

事件解绑。

• addShape(shape, attrs)
  

添加单个图形到画布。

• addGroup(attrs)
  添加单个组到画布。
  

通用方法

• attr()
  

设置或获取实例的绘图属性。

attr(name)

获取实例的属性值

const width = shape.attr('width');

attr(name, value)

更新实例的单个绘图属性

attr({…})

批量更新实例绘图属性

rect.attr({
    fill: '#999',
    stroke: '#666'
});

• set(name, value)
  

设置实例的属性，如visible, zIndex, id等。

• get(name)
  

获取实例的属性值

• show()
  

显示某实例对应的图形。

• hide()
  

隐藏某实例对应的图形

• remove()
  

删除实例本身

• destroy()
  

销毁实例

• setZIndex(zIndex)
  

更新某元素的层叠关系，并根据最新关系更新图形的绘制顺序。
注意:由于要对所有元素排序，批量更改层叠关系时建议使用set方法配合sort实现

• getBBox()
  

获取实例的包围盒

变换 Transform

• transform(ts)
  

实例变换方法。以数组形式，按顺序执行。
例如画布上有以下的一个矩形实例

const rect = canvas.addShape('rect', {
    attrs: {
        width: 100,
        height: 100,
        x: 100,
        y: 100,
        fill: 'red'
    }
});

在调用canvas.draw()后，得到的结果如图：

对其进行如下操作：

rect.transform([
    ['t', 100, 100],        // x方向平移100,y方向平移100
    ['s', 0.1, 1.2],        // x方向缩小0.1倍， y方向扩大1.2倍
    ['r', Math.PI / 4]        // 旋转45度
])

• translate(x, y)
  

实例的相对位移方法。

• move(x, y)
  

实例的相对位移方法。

• rotate(radian)
  

根据旋转弧度值对图形进行旋转。

• scale(sx, sy)
  

对图形进行缩放。

• resetMatrix()
  

清除图形实例的所有变换效果

• getTotalMatrix()
  

获取应用到实例上的所有变换的矩阵

动画 Animate

对某实例执行指定的动画。

参数

• attrs: Object
  

指定动画变更的绘图属性

• duration: number
  

动画执行时间

• easing
  

指定属性变化效果，可参见d3 ease，默认为easeLinear。

• callback
  

动画执行完成的回调函数

• delay
  

指定动画延迟时间(ms)。

animate(attrs, duration, easing, callback, delay = 0)

shape.animate({
    width: 200,
    height: 200,
    repeat: true      // 指定为重复动画
}, 1000);

组 Group

图形分组可以嵌套图形和分组。

声明实例

const group = new Group(cfgs);

实例方法

• addGroup(cfgs)
  

向分组中添加新的分组。

• addShape(type, cfgs)
  

向分组中添加新的图形。
注意：在分组上添加的clip， transform等会影响到该分组中的所有图形。G支持的图形及其绘图属性请见shape小节。

• contain(child)
  

该分组是否包含此元素。
返回值: boolean

• find(fn)
  

根据指定条件返回对应元素

const child = group.find(function(item) {
    return item.attr('fill') === 'red';    // 找到首个填充为红色的图形
});

• findById(id)
  

根据元素ID返回对应的实例。
返回值：Object

• findAll(fn)
  

返回所有符合条件的元素
返回值: [ Object ]

const children = group.findAll(function(item) {
    return item.get('id') < 10;       // 获取所有id小于10的元素
});

• getShape(x,y)
  

返回该坐标点最上层的元素。
返回值: Object

• getFirst()
  

获取该分组的第一个子元素
返回值: Object

• getLast()
  

获取该分组的最后一个子元素
返回值: Object

• getChildByIndex(index）
  

返回第index个子元素，从0开始计数。
返回值: Object

• removeChild(child)
  

从分组中删除一个分组或一个图形

• sort()
  

排序方法。一般用于在设置子元素层叠顺序时使用。

• clear()
  

清除该组的所有子元素

图形 Shape

通用属性见绘图属性小节。以下列出目前G支持的图形，及其特有的绘图属性。

圆 Circle

• x: 圆心的 x 坐标
  
• y: 圆心的 y 坐标
  
• r: 半径
  

椭圆 Ellipse

• x: 圆点的 x 坐标
  
• y: 圆点的y坐标
  
• rx: 水平半径
• ry: 垂直半径

扇形 Fan

• x: 扇形圆心的 x 坐标
  
• y: 扇形圆心的 y 坐标
  
• rs: 内圈半径
  
• re: 外圈半径
  
• startAngle: 起点弧度
  
• endAngle: 终点弧度
  
• clockwise: 为true时顺时针渲染，为false时逆时针渲染
  

图片 Image

• x: 图片左上角的 x 坐标
  
• y: 图片左上角的 y 坐标
  
• width: 图片宽度
  
• height: 图片高度
  
• img: 图片源。G支持多种格式的图片。
  • url
    
  • ImageData
    
  • Image
    
  • canvas
    

标记 Marker

可自定义的形状。

• x: 中心的 x 坐标
  
• y: 中心的 y 坐标
  
• r: 形状半径
  
• symbol：指定形状。G内置了一些常用形状，如圆形circle, 矩形 square, 菱形 diamond,三角形 triangle, 倒三角形triangle-down，也可以是自定义的path路径。
  

const marker = canvas.addShape('marker', {
    attrs: {
        x: 10,
        y: 10,
        r: 10,
        symbol: function(x, y, r) {
            return [
                [ 'M', x, y ],
                [ 'L', x + r, y + r ],
                [ 'L'，x + r * 2, y ],
                [ 'Z' ]
            ]
        }
    }
});

线条 Path

• path： 线条。可以是String形式，也可以是线段的数组。
  
• startArrow: 起始端的箭头。为true时为默认的箭头效果，也可以是一个自定义箭头。
  
• endArrow: 末尾端的箭头。为true时为默认的箭头效果，也可以是一个自定义箭头。
• lineAppendWidth: 为了提升边的击中范围，增加这个属性，扩展响应范围。

group.addShape('path', {
      attrs: {
        startArrow: {
          path: 'M 10,0 L -10,-10 L -10,10 Z',  // 自定义箭头为中心点在(0, 0)，指向 x 轴正方向的path
          d: 10
        },
        endArrow: {
          path: 'M 10,0 L -10,-10 L -10,10 Z',  // 自定义箭头为中心点在(0, 0)，指向 x 轴正方向的path
          d: 10
        },
          path: [
           [ 'M', 100, 100 ],
           [ 'L', 200, 200 ]
          ],
        stroke: '#000',
        lineWidth: 8
      }
    });

多边形 Polygon

• points: 多边形的所有端点坐标。数组形式。
  

  const polygon = canvas.addShape('polygon', {
    attrs: {
        points:[[ 30, 30 ], [ 40, 20 ], [ 30, 50 ], [ 60, 100 ]],
        fill: 'red'
    }
  });

矩形 Rect

• x: 矩形左上角的 x 坐标
  
• y: 矩形左上角的 y 坐标
  
• width: 矩形的宽度
  
• height: 矩形的高度
  
• radius: 定义圆角。支持整数或数组形式， 分别对应左上、右上、右下、左下角的半径。
  • radius缩写为 1或 [ 1 ] 相当于 [ 1, 1, 1, 1 ]
    
  • radius 缩写为 [ 1, 2 ] 相当于 [ 1, 2, 1, 2 ]
    
  • radius 缩写为 [ 1, 2, 3 ] 相当于 [ 1, 2, 3, 2 ]
    

    canvas.addShape('rect', {
    attrs: {
     x: 150,
     y: 150,
     width: 150,
     height: 150,
     stroke: 'black',
     radius: [2, 4]
    }
    });

文本 Text

• text: 文本内容。可以用\n定义多行文本。
  
• font: 设置文本内容的当前字体属性,这个属性可以分解成多个属性单独配置。
  • fontStyle：对应 font-style，默认为normal
    
  • fontVariant： 对应 font-variant，默认值为normal
    
  • fontWeight： 对应 font-weight，默认值为normal
    
  • fontSize：对应 font-size， 默认值为12
    
  • fontFamily：对应 font-family，默认值为sans-serif。
    
• textAlign: 文本内容的对齐方式, 支持的属性为：center|end|left|right|start，默认值为start。
  
• textBaseline: 绘制时的文本基线, 支持的属性:top|middle|bottom |alphabetic|hanging，默认值为bottom。
  

注意：文本的颜色一般使用 fill 属性，而非 ‘stroke’ 属性

canvas.addShape('text', {
    attrs: {
      x: 150,
      y: 150,
      fontFamily: 'PingFang SC',
      text: '文本文本',
      fontSize: 90,
      fill: 'black'
    }
  });
  canvas.addShape('text', {
    attrs: {
      x: 250,
      y: 250,
      fontFamily: 'PingFang SC',
      fontSize: 90,
      text: '这是第一行\n这是第二行',
      lineDash: [10, 10],
      fill: 'red'
    }
  });

通用绘图属性

g支持指定canvas 的属性，本章列出常用的属性，详细信息参考 canvas 属性。

通用属性

• fill 设置用于填充绘画的颜色、渐变或模式， 对应canvas属性fillStyle
  
• stroke 设置用于笔触的颜色、渐变或模式， 对应canvas属性strokeStyle
  
• shadowColor 设置用于阴影的颜色
  
• shadowBlur 设置用于阴影的模糊级别
  
• shadowOffsetX 设置阴影距形状的水平距离
  
• shadowOffsetY 设置阴影距形状的垂直距离
  
• opacity 设置绘图的当前 alpha 或透明值， 对应canvas属性globalAlpha
  
• globalCompositeOperation 设置新图像如何绘制到已有的图像上
  

文本属性

• font 设置文本内容的当前字体属性
  
• textAlign 设置文本内容的当前对齐方式, 支持的属性：center|end|left|right|start，默认值为start
  
• textBaseline 设置在绘制文本时使用的当前文本基线, 支持的属性:top|middle|bottom |alphabetic|hanging。默认值为bottom
  

注意：G 提供了额外的几个文本属性，便于用户设置字体，具体的含义参考font 组成

• fontStyle 对应 font-style；
  
• fontVariant 对应 font-variant；
  
• fontWeight 对应 font-weight；
  
• fontSize 对应 font-size；
  
• fontFamily 对应 font-family；
  

渐变色

G提供线性渐变，环形渐变两种形式。

• 线性渐变
  

说明：l 表示使用线性渐变，绿色的字体为可变量，由用户自己填写。

// 使用渐变色描边，渐变角度为 0，渐变的起始点颜色 #ffffff，中点的渐变色为 #7ec2f3，结束的渐变色为 #1890ff
stroke: 'l(0) 0:#ffffff 0.5:#7ec2f3 1:#1890ff'

• 环形渐变
  

说明：r 表示使用放射状渐变，绿色的字体为可变量，由用户自己填写，开始圆的 x y r 值均为相对值，0 至 1 范围。

// example
// 使用渐变色填充，渐变起始圆的圆心坐标为被填充物体的包围盒中心点，半径为(包围盒对角线长度 / 2) 的 0.1 倍，渐变的起始点颜色 #ffffff，中点的渐变色为 #7ec2f3，结束的渐变色为 #1890ff
fill: 'r(0.5, 0.5, 0.1) 0:#ffffff 1:#1890ff'

纹理

用特定的纹理填充图形。G支持的纹理内容可以直接是图片或者 Data URLs。

说明：p 表示使用纹理，绿色的字体为可变量，由用户自己填写。

• a: 该模式在水平和垂直方向重复；
  
• x: 该模式只在水平方向重复；
  
• y: 该模式只在垂直方向重复；
  
• n: 该模式只显示一次（不重复）。
  

shape.attr('fill', 'p(a)https://gw.alipay.com/cube.png');

裁剪

在某元素上添加形状裁剪。G支持的裁剪图形与绘制图形相同。

shape.attr('clip', new Circle({
    attrs: {
        x: 100,
        y: 100,
        r: 100
    }
}))

const clip = new Rect({
    attrs: {
        x: 50,
        y: 100,
        width: 100,
        height: 100
    }
});
const shape = canvas.addShape('marker', {
    attrs: {
        x: 20,
        y: 80,
        r: 200,
        symbol: 'diamond',
        clip: clip
    }
});

注意：最好使用单独的shape构造方法定义clip，否则每次重绘时会将裁剪图形也绘制一遍。

线条样式

• lineCap 设置线条的结束端点样式；
  
• lineJoin 设置两条线相交时，所创建的拐角形状；
  
• lineWidth 设置当前的线条宽度；
  
• miterLimit 设置最大斜接长度。
  
• lineDash：设置线的虚线样式，可以指定一个数组。一组描述交替绘制线段和间距（坐标空间单位）长度的数字。 如果数组元素的数量是奇数， 数组的元素会被复制并重复。例如， [5, 15, 25] 会变成 [5, 15, 25, 5, 15, 25]。
  

注意：这个属性取决于浏览器是否支持 setLineDash 函数，详情参考setLineDash。

鼠标样式

鼠标移动到图形上改变形状，可以通过更改 canvas.style.cursor 来实现，但是用户用起来非常麻烦，因此 G 提供了在图形属性中设置鼠标样式的功能：

• cursor : 鼠标样式，同 css 的鼠标样式,默认 ‘default’

group.addShape('circle', {
  attrs: {
      x: 0,
    y: 0,
    fill: 'red',
    r: 10,
    cursor: 'pointer'
  }
});
// 修改
circle.attr('cursor', 'default');