antv-g2学习手册-中

antv-g2学习手册-上

图形标注配置

图例标注(Annotation)作为G2图表的辅助元素，主要用于在图表上标识额外的标记注解。

图表标注类型

类型	描述	配置语法
arc	辅助弧线，只在极坐标系下生效。常用于绘制仪表盘	chart.annotaion().arc({})
image	辅助图片，在图表上添加辅助图片	chart.annotation().image({})
line	辅助线（可带文本），例如表示平均值或者预期分布的直线	chart.annotation().line({})
text	辅助文本，指定位置添加文本说明	chart.annotion().text({})
region	辅助框，框选一段图区，设置背景，边框等	chart.annotation().region({})
regionFilter	区域着色，将图表中位于矩形选区中的图形元素提取出来，重新作色	chart.annotation().regionFileter({})
dataMarker	特殊数据点标注，多用于折线图和面积图	chart.annotation().dataMarker({})
dataRegion	特殊数据区间标注，多用于折线图和面积图	chart.annotation().dataRegion({})

注：配置项详情请看源码

清空图形标注

chart.annotation().clear()清空所有的图形标注，但是不会清空配置，当用户再次调用chart.render()时，所有的annotation会重新绘制
chart.annotation().clear(true)清空所有的图形标注同时清空配置

动态图形标注

G2图形标注接受的位置信息的参数都是原始数据值，辅助标记一旦生成后就是固定了位置，如果数据发生改变，辅助标记就需要删除掉重新创建。
如果数据是动态更新的那么这个过程需要频繁进行，基于这种场景Annotation提供了如下两种解决方案：

• 可以使用’min’,‘median’,'max’关键字，代表原始值的最小值、平均值、最大值，例如:[0,‘min’]表示x轴上数值为0，y轴位置在数值的最小值上;
• 表示位置的数组可以换成回调函数，函数原型:function(xScale,yScales){return [];}
  注：XScale，yScale分别对应x轴的度量和所有y轴的度量

文本标签配置

在图表中，标签是对当前的一组数据进行的内容标注。文本标签可包括数据点、拉线、文本数值等元素，根据不同的图表类型选择使用

如何显示文本标签

文本标签对应每一条数据记录，G2除了提供文本标签的显示功能外，还可以使用geometry.label()指定显示的内容、配置文本样式等

文本标签类型

针对不同的图表类型有不同的文本标签类型。G2默认提供了4种类型：

• ‘base’,默认类型，用于直角坐标系下的图表
• ‘interval’，用于interval几何标记下所有图形的文本标注，比如‘柱状图’等
• ‘pie’，专用于饼图的文本标注，带有文本连接线
• ‘polar’，用于极坐标系下图表的文本标注

G2已经根据用户声明的图形语法自动使用对应的文本标签类型，用户不需要再额外声明。但是当有特殊需求时（比如自定义了文本标签），用户可以通过label()接口中的type属性指定具体的文本标签类型

标签布局

对于文本标签，当数据过于密集是，就会存在文本遮挡重叠的问题。
G2内置了三种文本布局方案

• overlap:label防遮挡，为了防止label之间相互覆盖，通过尝试向四周偏移来剔除放不下的label
• fixedOverlap:不改变label位置的情况下对相互折叠的label进行调整
• limitlnShape:剔除shape容纳不了的label

配置方式：

geometry.label(name,{layout:{type:'fixed-overlap'}})

图表动画配置

动画类型

G2根据数据的装载更新，将动画分为以下四类：

动画类型	解释
appear	图表第一次加载时的入场动画
enter	图表绘制完成，发生更新后，产生的新图形的进场动画
update	图表绘制完成，数据发生变更后，有状态变更的图形的更新动画
leave	图标绘制完成，数据发生变更后，被销毁图形的销毁动画

参与动画的元素

G2图表中默认参与动画的元素

• Geometry shapes
• Geometry labels
• 图表组件Component
• Axis
  • ticks
  • labels
  • grid
• Annotation

注意：G2位Geometry shapes内置了初始化时的群组入场动画，如果自己配置的有appear动画执行函数，则以该动画为主。

动画配置

G2在Chart/View,Geometry,Geometry Label 以及组件层次都开放了动画接口，即只要是参与动画的图形元素都可以单独进行动画配置

chart

chart.animate(boolean) 开启或者关闭chart动画
注：当chart.animate(false)关闭动画时，该图表所有的元素都不会进行动画

view

view.animate(boolean) 开启或者关闭view上的动画
注：当view.animate(false)关闭动画时，该试图下所有的元素都不会进行动画

Geometry

包含Geometry Shapes 以及 Geometry labels

geometry.animate(false);//Geometry不执行动画
getmetry.animate(cfg);//进行具体的动画配置，详见:base.d.ts 456

Geometry label 上的动画配置

geometry.label(name,{
	animate:AnimateOption | false //详见:base.d.ts 491
})

图表组件

对于图表组件的动画，G2只支持开关操作

chart.axis(name:{
	animate:boolean
})
chart.annotation().line({
	animate:boolean
})

内置默认动画函数

animation	说明
‘fade-in’	渐现动画
‘fade-out’	渐隐动画
‘grow-in-x’	容器沿x方向放大的矩阵动画，多用于G.Group容器类进行动画
‘grow’-in-y	容器沿着y方向放大的矩阵动画，多用于G.Group容器类进行动画
‘grow-in-xy’	容器沿着x,y方向放大的矩阵动画，多用于G.Group容器类进行动画
‘scale-in-x’	单个图形沿着x方向的生长动画
‘scale-in-y’	单个图形沿着y方向的生长动画
‘wave-in’	划入入场动画效果，不同坐标系下效果不同
‘zoom-in’	沿着图形中心点的放大动画
‘zoom-out’	沿着图形中心点的缩小动画
‘path-in’	path路径入场动画
‘position-update’	图形位置移动动画

配置图标主题

G2在绘图时，首先会确定数据是如何展示的，然后再通过主题系统对细节进行控制。在G2中主题控制着图表的非数据元素外观，包括图表的坐标轴、图例、网格线等的样式及几何标记的颜色搭配等
可以在G2中：

1. 使用内置主题
2. 修改内置主题的某些元素
3. 注册自定义元素

使用内置主题

G2提供了一种内置主题，命名为‘default’。同时可以使用以下方法对主题进行切换或者修改

1. 在初始化chart时指定

const chart =new Chart({
	container:'container',
	theme:'dark',//使用命名为dark的主题
});

const chart1 = new Chart({
	container:'container',
	theme:{
		defaultColor:'red'
	}//修改内置主题的某些配置
})

2. 通过chart.theme()接口配置

//创建图表的时候切换主题
chart.theme('dark');
chart.render();//渲染图表
//图表渲染后，动态切换主题
chart.theme({
	defaultColor:'red'
})//修改内置主题的某些配置
chart.render(true);

注意：chart.theme()声明之后，必须调用chart.render()/chart.render(true)方可生效,如果是动态切换主题场景，建议调用chart.render(true)

3. 在view上配置主题

//在创建view的时候声明主题
const view = chart.createView({theme:'dark'})
//在创建view的时候修改主题
const view =chart.createView({
	theme:{defaultColor:red}
})
//通过theme()接口声明
view.theme('dark');
view.theme({
	defaultColor:'red'
})

注：view.theme()声明之后，必须调用chart.render()/chart.render(true)生效，如果是动态切换主题场景，建议调用chart.render(true)

4. 在Geometry上配置主题

chart.interval({
	theme:{
		defaultColor:'red'
	}
})

注册自定义主题

G2提供了自定义主题机制以允许用户切换，定义图表主题。包括：

1. 定义全新的主题结构
2. 使用主题样式表，实现主题的快速定制

定义全新的主题结构

import {registerTheme,Chart} from '@antv/g2'
//注册主题
registerTheme(name,{
	defaultColor:'red'
})
//使用
chart.theme(name);
chart.render()

主题属性

主题属性	类型	描述
defaultColor	string	主题色
padding	number	间隔
fontFamily	string	图表字体
colors10	string[]	分类颜色色板，分类个数小于10使用
colors20	string[]	分类颜色色板，分类个数大于10使用
columnWidthRatio	number	一般柱状图宽度占比，0-1范围数值
maxColumnWidth	number	柱状图最大宽度，像素值
minColumnWidth	number	柱状图最小宽度，像素值
roseWidthRatio	number	玫瑰图占比，0-1范围数值
multiplePiewWidthRatio	多层饼图/环图占比，0-1范围数值
shapes	object	配置每个Geometry映射的shape类型
sizes	number	配置geometry映射size范围
geometries	object	配置每个Geometry下每个shape的样式，包括默认样式以及各个状态下的样式
components	object	配置坐标轴，图例，tooltip，annotation的主题样式
labels	object	配置Geometry下label的主题样式
innerLabels	object	配置Geometry下展示在图形内部的labels的主题样式
pieLabels	object	配置饼图labels的主题样式

使用数据调整

数据调整可以使得图形在画布上不互相重叠
G2支持以下数据调整:

stack(层叠)

将同一个分类的数据值累加起来。以层叠的柱状图为例，x轴方向的同一个分类下面的数据，按照顺序，将y轴对应的值累加，最终将数据调整的不再层叠

适合的数据类型

层叠数据，适用于分类数据和连续数据，只要x轴方向的值相同，就会对y轴方向的值进行层叠处理

适合的几何标记

几何标记	描述	配置
point	层叠的点图	chart.point().adjust(‘stack’)
interval	层叠的柱状图、玫瑰图	chart.interval().adjust(‘stack’)

jitter(扰动散开)

将数据的位置轻微的调整，使得映射后的图形位置不再重叠

适合的数据类型

jitter,仅适合于分类数据，只能在同一个分类的范围内散开，这不会改变图形表现的分类值。但是连续数据不能进行散开，连续数据位置一旦变化，图形代表的数据值就会不准确，会带来误导。对数据进行jitter调整时，需要将分类数据转换成索引值，在索引值[-0.5,0.5]的范围内进行随机分布

适合的几何标记

几何标记	描述	配置
point	散开的点图	chart.point().adjust(‘jitter’)

dodge(分组散开)

将同一个分类的数据进行分组在一个范围内均匀分布

适合的数据

dodge是将同一个分类的数据均匀的分布的范围内，形成分组效果，同样不适合连续数据。dodge跟jitter的差别在于：

• dodge的数据在分类范围内将数据均匀分布
• 如果数据只有一维，y轴方向无数据，那么jitter在整个y轴方向随机分布，而dodge在y轴方向层叠分布

适合的几何标记

几何标记	描述	配置
point	一维点图	chart.point().adjust(‘dodge’)
interval	二维的柱状体、玫瑰图	chart.interval.adjust(‘dodge’)

symmetric(数据对称)

使得生成的图形居中对齐

适合的数据

symmetric将数据沿y轴进行对称处理，所以适合处理连续数据。由于对称处理将单个值的数据处理成了有上下限的数值，所以不会引起数据的误解
计算公式：offset = (max-min-value)/2

适合的几何标记

几何标记	描述	配置
interval	漏斗图	chart.interval().adjust(‘symmetric’)
area	数据流图：对称的层叠区域图	chart.area().adjust(‘symmetric’)

数据调整的原则

1. 不改变数据的含义，给用户带来误解
2. 数据调整的界限要清晰，不能混淆不同类别的数据
3. 定量（连续）数据只能进行数据的累加和对称，分类数据只能在当前分类的范围内调整数据

图表事件使用

G2提供的事件机制有：

1. Chart/View声明周期的事件
2. 基础的画布事件
3. 数据映射到图形Element上的事件
4. 组件上的事件
   这些事件都可以在Chart和View上进行绑定和移除绑定

绑定和解除绑定

在Chart和View上提供几个方法用于绑定事件、移除绑定事件：

-on('eventName',callback(event){})绑定事件
-off('eventName',[callback])移除事件

event 对象

Chart和Shape的事件抛出的事件对象event上包含以下属性:

• target:触发的对象，图形或者Canvas对象
• view:当前target所属的view
• gEvent:从底层G的绘图层抛出来的事件。详情参考:G的事件详解
• event:dom层的事件
• x:触发的位置x，相对于画布左上角的位置
• y：触发的位置y，相对于画布左上角的位置
• clientX:视窗的位置x
• clientY:视窗的位置y

生命周期的事件

Chart和View的生命周期提供了以下事件

• beforeender：事件发生在渲染前
• afterrender: 事件发生在渲染后
• beforepaint: 组件，图形元素绘制前
• afterpaint: 组件，图形元素绘制后
• beforechangedata: 更新数据前
• afterchangedata : 更新数据后
• beforeclear：调用clear方法清除View或者Chart前触发
• afterclear：调用clear方法清除View或者Chart前触发
• beforedestroy：销毁View或者Chart前触发

基础的画布事件

可以在Chart和view上监听所有的浏览器事件，G实现了DOM具备的常用事件

• mousedown
• mouseup
• dblclick
• mouseenter
• mouseout
• mouseover
• mousemove
• mouseleave
• contaxtmenu
• click

拖拽事件通过mousedown，mousemove和mouseup进行了模拟

• dragstart
• drag
• dragend
• dragover
• dragenter
• dragleave
• drop

同时支持了移动端的几个事件

• touchstart
• touchmove
• touchend

注：这些事件的事件对象可以通过event.gEvent访问到，事件上的具体属性可以参考：G的事件详解

图形Element上的事件

所有的图表绘图区域的图形都能响应各种事件，这些图形被封装成了图表元素Element，所有的基础画布事件都可以支持，为了便于使用，我们提供了委托事件的方式来方便用户绑定，其形式为name:eventName,主要有三种name:

• 所有的Element都支持‘element：eventName’的方式绑定事件，如‘element：click’
• 不同的geometry各自支持不同的前缀，等同于geometry.type,例如：‘line’，‘area’
• 用户在自定shape中，在shape，group上设置name字段

事件上的Element属性

可以通过shape.get(‘element’)对象来获取访问图形对应的Element对象

view.on('element:click',(ev)=>{
	const shape =ev.shape;
	const element =shape.get('element');
	const data =element.getModel().data
})

图形element上支持的name的列表

G2默认支持的所有的事件前缀（name）:

• element：所有的geometry的element都支持的事件前缀
• line：折线图支持的前缀
• interval：柱状图、直方图、饼图等支持的事件前缀
• point：点图、气泡图等支持的前缀
• schema：k线图、 箱型图支持的事件前缀
• edge：边支持的前缀

注意：

• 除了element是通用的事件前缀外，所有的geometry的type就是它们事件的前缀
• heatmap由于未创建任何element所以不支持任何事件前缀
• element上的获取返回的数据有些是单条数据，有些是多条数据的集合

状态事件

当Element上的状态发生改变时，会释放’element:statechange’事件，用户可以在Chart/View上监听该事件

chart.on('element:statechange',(eventObject)=>{
	const {element,state,stateStatus} = eventObject.gEvent.originalEvent;
	//获取触发该事件的element，当前的状态，状态值
})

组件上的事件

组件同Element一样都支持name:eventName的委托事件，不同的组件上支持不同的事件名前缀，这些事件名前缀可以同基础画布的事件组合使用，这些事件名有：

axis

• axis-label：坐标轴文本的事件的前缀
• axis-line：坐标轴轴线的事件前缀
• axis-tick：坐标轴刻度线的事件前缀
• axis-title：坐标轴标题事件前缀

legend

• legend：图例的事件前缀，无论点击了图例的任意图形上
• legend-title：图例标题的事件前缀
• legend-item：图例选项的事件前缀
• legend-item-name：图例选项name文本的事件前缀
• legend-item-maker：图例选线marketing图标的事件前缀
• legend-item-value：图例选项value的事件前缀

annotation

• annotation：所有辅助图形共同的事件前缀
• annotation-line：辅助线的事件前缀
• annotation-line-text：辅助线上的文本前缀
• annotation-image：辅助图形的事件前缀
• annotation-region：辅助区域的事件前缀
• annotation-text：辅助文本的事件前缀

tooltip

• tooltip:show
• tooltip:hide
• tooltip:change

连续图例

legend:valuechanged

委托对象

chart.on('lengend-item:click',(ev)=>{
	const target = ev.target;
	//所有的组件事件都可以从target上获得delegateObject
	const delegateObject = target.get('delegateObject');
	const item = delegateObject.item;//图例选项
	const component=delegateObject.component; //公有属性component属性
})

antv-g2学习手册-上
antv-g2学习手册-下