快速上手


安装

推荐通过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);



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


实例方法

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


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


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


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


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


绑定事件。

支持浏览器的常见事件:click|dblclickmouseentermouseleavemouseovermouseupmousedownmousemovetouchstarttouchend

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


事件解绑。


添加单个图形到画布。



通用方法


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


attr(name)

获取实例的属性值

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


attr(name, value)

更新实例的单个绘图属性


attr({...})

批量更新实例绘图属性

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


设置实例的属性,如visiblezIndexid等。


获取实例的属性值


显示某实例对应的图形。


隐藏某实例对应的图形


删除实例本身


销毁实例


更新某元素的层叠关系,并根据最新关系更新图形的绘制顺序。

注意:由于要对所有元素排序,批量更改层叠关系时建议使用set方法配合sort实现


获取实例的包围盒


变换 Transform


实例变换方法。以数组形式,按顺序执行。

例如画布上有以下的一个矩形实例


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度
])




实例的相对位移方法。


实例的相对位移方法。


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


对图形进行缩放。


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


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


动画 Animate


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


参数


指定动画变更的绘图属性


动画执行时间


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


动画执行完成的回调函数


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


animate(attrs, duration, easing, callback, delay = 0)
shape.animate({
    width: 200,
    height: 200,
    repeat: true    // 指定为重复动画
}, 1000);


组 Group


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


声明实例
const group = new Group(cfgs);


实例方法

向分组中添加新的分组。


向分组中添加新的图形。

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


该分组是否包含此元素。

返回值: boolean


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

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


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

返回值:Object


返回所有符合条件的元素

返回值: [ Object ]


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


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

返回值: Object


获取该分组的第一个子元素

返回值: Object


获取该分组的最后一个子元素

返回值: Object


返回第index个子元素,从0开始计数。

返回值: Object


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


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


清除该组的所有子元素


图形 Shape


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


圆 Circle


椭圆 Ellipse


扇形 Fan


图片 Image


标记 Marker

可自定义的形状。


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


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
const polygon = canvas.addShape('polygon', {
    attrs: {
        points:[[ 30, 30 ], [ 40, 20 ], [ 30, 50 ], [ 60, 100 ]],
        fill: 'red'
    }
});


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


文本 Text

注意:文本的颜色一般使用 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 属性


通用属性


文本属性



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



渐变色


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 表示使用纹理,绿色的字体为可变量,由用户自己填写。


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,否则每次重绘时会将裁剪图形也绘制一遍。


线条样式


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


鼠标样式

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


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

// 修改
circle.attr('cursor', 'default');