API - 配置项支持 - 《G2 2.x 使用教程》

配置项属性

G2 从 2.3.0 版本开始支持图形语法的配置项式声明方式。

为 Chart 对象新增 options 属性，用于支持配置项式声明。

var chart = new G2.Chart({
    width: 1000,
  height: 500,
  data: data,
  plotCfg: {
      margin: [20, 80, 60, 80]
  },
  options: {
      // 在这里声明所有的配置属性
  }
});
chart.render();

可以先通过以下几个例子来了解下：

实例 1：柱状图

var data = [
  {genre: 'Sports', sold: 275},
  {genre: 'Strategy', sold: 115},
  {genre: 'Action', sold: 120},
  {genre: 'Shooter', sold: 350},
  {genre: 'Other', sold: 150},
];
var chart = new G2.Chart({
  id: 'c1',
  forceFit: true,
  height: 300,
  data: data,
  options: {
    scales: {
      'genre': {
        alias: '游戏种类'
      },
      'sold': {
        alias: '销售量'
      }
    },
    geoms: [
      {
        type: 'interval',
        position: 'genre*sold',
        color: 'genre'
      }
    ]
  }
});
chart.render();

对应函数式调用代码如下：

var chart = new G2.Chart({
  id: 'c1',
  height : 300,
  forceFit: true,
});
chart.source(data, {
  genre: {
    alias: '游戏种类'
  },
  sold: {
    alias: '销售量'
  }
});
chart.interval().position('genre*sold').color('genre')
chart.render();

实例 2: 散点图

$.getJSON('../../static/data/scatter.json', function(data){
  var frame = new G2.Frame(data);
  var hAvg = G2.Frame.mean(frame,'height'); // 计算体重的均值
  var wAvg = G2.Frame.mean(frame,'weight'); // 计算身高均值
  var lineCfg = { // 线的配置信息
    stroke: '#94E08A'
  };
  var chart = new G2.Chart({
    id: 'c2',
    forceFit: true,
    height: 450,
    data: data,
    options: {
      scales: {
        weight: {
          alias: '体重（kg）'
        },
        height: {
          alias: '身高（cm）'
        }
      }, // 列定义
      tooltip: {
        title: null,
        crosshairs: {
          type: 'cross'
        }
      },
      axes: {
        'height': {
          formatter: function(val) {
            return val + ' cm';
          }
        }
      },
      guides: [
        {
          type: 'tag',
          from: [hAvg, 'min'],
          to: [hAvg, 'max'],
          text: '身高平均值: ' + hAvg.toFixed(2),
          cfg: {
            line:lineCfg
          }
        },
        {
          type: 'tag',
          from: ['min', wAvg],
          to: ['max', wAvg],
          text: '体重平均值: ' + wAvg.toFixed(2),
          cfg: {
            line:lineCfg
          }
        },
      ],
      geoms: [
        {
          type: 'point',
          position: 'height*weight',
          color: {
            field: 'gender',
            colors: ['rgba(223, 83, 83, 0.7)', 'rgba(119, 152, 191, 0.7)']
          },
          shape: {
            field: 'gender',
            shapes: ['circle', 'diamond']
          },
          size: 6,
          tooltip: 'gender*height*weight'
        }
      ]
    }
  });
  chart.render();
});

对应函数式调用代码如下：

var chart = new G2.Chart({
  id: 'c2',
  forceFit: true,
  height: 450
});
chart.source(data, {
  weight: {
    alias: '体重（kg）'
  },
  height: {
    alias: '身高（cm）'
  }
});
chart.tooltip({
  title: null,
  crosshairs: {
    type: 'cross'
  }
});
chart.point().position('height*weight').color('gender', ['rgba(223, 83, 83, 0.7)', 'rgba(119, 152, 191, 0.7)']).shape('gender', ['circle', 'diamond']).size(6).tooltip('gender*height*weight');
chart.guide().tag([hAvg, 'min'], [hAvg, 'max'], '身高平均值: ' + hAvg.toFixed(2), {line:lineCfg});
chart.guide().tag(['min', wAvg], ['max', wAvg], '体重平均值: ' + wAvg.toFixed(2), {line:lineCfg});
chart.render();

实例 3：多 views

$.getJSON('../../static/data/world.geo.json', function(mapData) {
  var userData = [
    {name: 'Russia',value: 86.8},
    {name: 'China',value: 106.3},
    {name: 'Japan',value: 94.7},
    {name: 'Mongolia',value: 98},
    {name: 'Canada',value: 98.4},
    {name: 'United Kingdom',value: 97.2},
    {name: 'United States of America',value: 98.3},
    {name: 'Brazil',value: 96.7},
    {name: 'Argentina',value: 95.8},
    {name: 'Algeria',value: 101.3},
    {name: 'France',value: 94.8},
    {name: 'Germany',value: 96.6},
    {name: 'Ukraine',value: 86.3},
    {name: 'Egypt',value: 102.1},
    {name: 'South Africa',value: 101.3},
    {name: 'India',value: 107.6},
    {name: 'Australia',value: 99.9},
    {name: 'Saudi Arabia',value:130.1},
    {name: 'Afghanistan',value: 106.5},
    {name: 'Kazakhstan',value:93.4},
    {name: 'Indonesia',value: 101.4}
  ];
  var Frame = G2.Frame;
  var Stat = G2.Stat;
  var frame = new Frame(userData);
  frame.addCol('trend', function(obj) {
    return (obj.value > 100) ? 1 : 0;
  });
  var map = [];
  var features = mapData.features;
  for(var i=0; i<features.length; i++) {
    var name = features[i].properties.name;
    map.push({
      "name": name
    });
  }
  var chart = new G2.Chart({
    id: 'c3',
    forceFit: true,
    height: 450,
    syncXYScales: true, // 统一视图的度量
    plotCfg: {
      margin: [55, 20]
    },
    data: map,
    options: {
      tooltip: {
        title: null
      },
      legends: {
        'trend': {
          position: 'left'
        }
      }
    }
  });
  // 绘制世界地图背景
  var view = chart.createView({
    data: map,
    options: {
      tooltip: false,
      geoms: [
        {
          type: 'polygon',
          position: Stat.map.region('name', mapData),
          shape: 'stroke',
          style: {
            fill: '#fff',
            stroke: '#ccc',
            lineWidth: 1
          }
        }
      ]
    }
  });
  // 绘制展示数据
  var userView = chart.createView({
    data: frame,
    options: {
      scales: {
        'trend': {
          type: 'cat',
          alias: '每100位女性对应的男性数量',
          values: ['女性更多', '男性更多']
        }
      },
      geoms: [
        {
          type: 'polygon',
          position: Stat.map.region('name*value', mapData),
          color: {
            field: 'trend',
            colors: ['#C45A5A','#14647D']
          },
          opacity: 'value',
          tooltip: 'name*trend'
        }
      ]
    }
  });
  chart.render();
});

对应的函数式调用代码如下：

var chart = new G2.Chart({
  id: 'c3',
  forceFit: true,
  height: 450,
  syncXYScales: true, // 统一视图的度量
  plotCfg: {
    margin: [55, 20]
  }
});
chart.tooltip({
  title: null
});
chart.legend('trend', {
  position: 'left'
});
// 绘制世界地图背景
var view = chart.createView();
view.source(map);
view.tooltip(false);
view.polygon().position(Stat.map.region('name', mapData)).shape('stroke').style({
  fill: '#fff',
  stroke: '#ccc',
  lineWidth: 1
});
// 绘制展示数据
var userView = chart.createView();
userView.source(frame, {
  'trend': {
    type: 'cat',
    alias: '每100位女性对应的男性数量',
    values: ['女性更多', '男性更多']
  }
});
userView.polygon().position(Stat.map.region('name*value', mapData)).color('trend',['#C45A5A','#14647D']).opacity('value').tooltip('name*trend');
chart.render();

配置项属性

var options = {
  appendFields: {Array}, // 作为附加字段，用于补全数据源中的数据字段，常用于数据源含有不同数据字段的记录
  scales: {Object}, // 列定义声明
  coord: {Object}, // 坐标系配置
  axes: {Object}, // 坐标轴配置
  legends: {Object}, // 图例配置
  guides: {Array}, // 图表辅助元素配置
  filters: {Object}, // 数据过滤配置
  tooltip: {Object}, // 提示信息配置
  facet: {Object}, // 分面配置
  geoms: {Array}, // 图形语法相关配置
}

appendFields

类型： Array

对应 chart.source(data[, colDefs, namesArr]) 方法中的 namesArr 参数，用于补全数据源中所有的字段属性。

scales

类型： Object

用于定义所有的列定义。对应以下 api chart.cols()，chart.col()，chart.source() 。

具体使用方式如下

scales: {
  ${field1}: {Object}, // 为数据字段 field1 进行列定义
  ${field2}: {Object}, // 为数据字段 field2 进行列定义
  ...
}

具体列定义的参数 API： Scale。

代码示例，为以下数据源的 time value 两个数据字段定义对应的列定义：

var data = [
  {"value":10,"time":"2015-03-01T16:00:00.000Z"},
  {"value":15,"time":"2015-03-01T16:10:00.000Z"},
  {"value":26,"time":"2015-03-01T16:20:00.000Z"},
  {"value":9,"time":"2015-03-01T16:30:00.000Z"},
  {"value":12,"time":"2015-03-01T16:40:00.000Z"},
  {"value":23,"time":"2015-03-01T16:50:00.000Z"},
  {"value":18,"time":"2015-03-01T17:00:00.000Z"},
  {"value":21,"time":"2015-03-01T17:10:00.000Z"},
  {"value":22,"time":"2015-03-01T17:20:00.000Z"}
];
var chart = new G2.Chart({
  id: 'c1',
  forceFit: true,
  height: 300,
  data: data,
  options: {
    scales: {
    'time': {
      type: 'time',
      nice: false,
      mask: 'HH:MM'
      },
      'value': {
      formatter: function(val) {
          return val + ' k';
      }
      }
  }
  }
});
// 配置项声明同函数调用可以混合使用
chart.line().position('time*value').color('red');
chart.render();

coord

类型： Object

坐标系配置，函数式调用 api：chart.coord(type, cfg)。

具体配置方式如下：

coord: {
  type: {String}, // 坐标系类型声明，可取值: rect polar theta map helix gauge clock
  cfg: {Object}, // 对应各个 type 坐标系属性配置，同 `chart.coord(type, cfg)` 中的 cfg
  actions: {Array} // 声明坐标系需要进行的变换操作
}

actions 属性的声明方式如下:

actions: [
  ['transpose'],
  ['rotate', 90],
  ['scale', 1, -1],
  ['reflect', 'x']
]

axes

类型：Object

图表坐标轴配置，对应 chart.axis(dim, cfg) 方法。

具体使用方式：

不展示坐标轴

axes: {
  visible: false
}

不展示某条坐标轴

axes: {
  ${fields}: false, // 不展示数据字段 field1 对应的坐标轴
}

或者

axes: {
  ${fields}:
    visible: false
  }, // 不展示数据字段 field1 对应的坐标轴
}

为各个的坐标轴进行配置

axes: {
   ${field1}: {Object}, // 具体配置同 https://antv.alipay.com/g2/api/chart.html#axis
   ${field2}: {Object}, // 具体配置同 https://antv.alipay.com/g2/api/chart.html#axis
   // ...
}

legends

类型： Object

图表图例配置，对应 chart.legend()。

不显示所有的图例

legends: {
  visible: false
}

为默认的图例进行配置

legends: {
  position: 'right', // 图例的显示位置，有 'top','left','right','bottom'四种位置，默认是'right'
  // ... 其他属性同 https://antv.alipay.com/g2/api/chart.html#chart-legend-cfg
}

为各个数据字段对应的图例进行配置

legends: {
  ${field1}: {Object}, // 具体的配置属性同 https://antv.alipay.com/g2/api/chart.html#chart-legend-dim-cfg
  ${field2}: false // 不展示 field2 对应的图例 
}

guides

类型：Array

图表辅助元素定义，对应 chart.guide()。

 [
    {
      type: 'line', // 添加辅助线
      from: {Array}, // 辅助线起始点，[startX, startY]
      to: {Array}, // 辅助线结束点，[endX, endY]
      cfg: {
        stroke: '#999', // 线的颜色
        lineDash: [0, 2, 2], // 虚线的设置
        lineWidth: 3 // 线的宽度
      } // {object} 配置项,与原语法相同
    },
    {
      type: 'image', // 添加辅助线
      from: {Array}, // 辅助图片起始点，[startX, startY]
      to: {Array}, // 辅助图片结束点，[endX, endY]
      cfg: {
        src: 'http://gtms02.alicdn.com/VXXXXaZX.png', // 图片路径
        width: 160, // 宽度，可以不设置，如果设置了 [endXValue, startYValue]，此属性无效
        height复制代码: 230 // 高度，可以不设置，如果设置了 [endXValue, endYValue]，此属性无效
      } // {object} 配置项,与原语法相同
    },
    {
      type: 'text',
      from: {Array}, // 文本起始点，[startX, startY]
      text: {String}, // 辅助文本内容
      cfg: {
        fill: '#666', // 文本颜色
        fontSize: '12', // 文本大小
        fontWeight: 'bold' // 文本粗细
      } // {object} 辅助文本的显示样式配置
    }, {
      type: 'rect',
      from: {Array}, // 辅助框起始点，[startX, startY]
      to: {Array}, // 辅助框结束点，[endX, endY]
      cfg: {
        lineWidth: 0, // 辅助框的边框宽度复制代码
        fill: '#f80', // 辅助框填充的颜色
        fillOpacity: 0.1, // 辅助框的背景透明度
        stroke: '#ccc' // 辅助框的边框颜色设置
      } // {object} 辅助框的显示样式配置
    }, {
      type: 'tag',
      from: {Array}, // 辅助标记起始点，[startX, startY]
      to: {Array}, // 辅助标记结束点，[endX, endY]
      text: {String}, // 辅助文本
      cfg: {
        line: {
          stroke: '#999',
          lineDash: [0, 2, 2]
        }, // 辅助标记中连接线的样式配置
        text: {
          fill: '#666',
          fontSize: '12',
          textAlign: 'center'
        }, // 辅助标记中文本的样式配置
        rect: {
          lineWidth: 0,
          fill: '#999',
          fillOpacity: 0.1
        } // 辅助标记中背景框的样式配置
      } // {object} 辅助标记的显示样式配置，[x, y]
    },
    {
      type: 'arc',
      from: {Array}, // 辅助弧线起始点，[startX, startY]
      to: {Array}, // 辅助弧线结束点，[endX, endY]
      text: {String}, // 辅助文本
      cfg: {
        stroke: '#999', // 线的颜色
        lineDash: [0, 2, 2], // 虚线的设置
        lineWidth: 3 // 线的宽度
      } // {object} 辅助弧线的显示样式配置
    },
    {
      type: 'html',
      from: {Array}, // html dom 元素的起始点，[startX, startY]
      html: {String}, // 辅助 html 的自定义内容
      cfg: {
        align: 'tr' | 'tc' | 'tl' | 'br' | 'bc' | 'bl' | 'lc' | 'rc' | 'cc', // 对齐方式
        offset: {Array} // 偏移坐标，[x, y]
      } // {object} 辅助 html 的配置项
    }
  ]

filters

类型：Object

数据过滤，对应 chart.filter(dim, remained)

filters: {
  ${field1}: {Array}, // 对字段名为 field1 的数据进行过滤
  ${field2}: {Array}, // 对字段名为 field2 的数据进行过滤
  ...
}

类型：Object

对应 chart.tooltip

tooltip: {
  visible: {Boolean}, // 开启关闭 tooltip 功能
  title: null, // 用于控制是否显示 tooltip 框内的 title
  map: { // 用于指定 tooltip 内显示内容同原始数据字段的映射关系复制代码
    title: '数据字段名或者常量', // 为数据字段名时则显示该字段名对应的数值，常量则显示常量
    name: '数据字段名或者常量', // 为数据字段名时则显示该字段名对应的数值，常量则显示常量复制代码
    value: '数据字段名' // 为数据字段名时则显示该字段名对应的数值
  },
  offset: 15, // 偏移量，设置 tooltip 显示位置距离 x 轴方向上的偏移
  crosshairs: true, // 是否展示 tooltip 的辅助线，默认为 false，不展示
  crossLine: {
    stroke: '#666', // 辅助线的颜色
    lineWidth: 2, // 辅助线的宽度
    lineDash: [2, 3] // 设置虚线样式
  }, // crosshairs 为 true 时，为辅助线设置样式
  padding: [10, 10, 10, 10], // 提示框内边距
}

当需要使用自定义的 html 模板生成 tooltip 时，需要对 tooltip 进行如下配置：

tooltip: {
  custom: true, // 表示使用自定义的模板显示 tooltip
  html: '<div class="ac-tooltip" style="position:absolute;visibility: hidden;"><h4 class="ac-title"></h4><table class="ac-list custom-table"></table></div>', // tooltip 的 html 外层模板
  itemTpl: '<tr><td>{index}</td><td style="color:{color}">{name}</td><td>{value}k</td></tr>', // 使用 html 时每一个显示项的模板，默认支持 index, color, name, value 这四个字段。
  offset: 50, // 偏移量，设置tooltip 显示位置距离 x 轴方向上的偏移
  customFollow: false // 设置 tooltip 是否跟随鼠标移动，默认为 true，跟随。
}

类型：Object

对应 chart.facet()。

facet: {
  fields: {Array}, // 用于切割分面的数据源字段，是一个数组 Array。
  type: 'rect' | 'list' | 'circle' | 'tree' | 'mirror', // 设置分面的布局类型
  margin: 10, // 各个分面之间的距离，同 CSS 盒模型中的 margin
  facetTitle: { // 各个分面标题的样式配置
    titleOffset: 16, // 标题距离内容区的偏移
    colDimTitle: {
      title: {
        fontSize: 14,
        textAlign: 'center',
        fill: '#999'
      }
    },
    colTitle: {
      title: {
        fontSize: 12,
        textAlign: 'center',
        fill: '#999'
      }
    },
    rowTitle: {
      title: {
        fontSize: 12,
        textAlign: 'center',
        rotate: 90,
        fill: '#999'
      }
    },
    rowDimTitle: {
      title: {
        fontSize: 12,
        textAlign: 'center',
        rotate: 90,
        fill: '#999'
      }
    }
  }
}

对于不同的分面类型有以下的配置项：

rect 矩阵分面

无

list 列表型分面

facet: {
field: {Array}, // 用于切割分面的数据源字段，是一个数组 Array。
type: 'list',
cols: 2 // 每行有只展示 2 个分面，超过 2 个则自动折行
}

circle 圆形分面

facet: {
field: {Array}, // 用于切割分面的数据源字段，是一个数组 Array。
type: 'circle'
}

tree 树形分面

facet: {
field: {Array}, // 用于切割分面的数据源字段，是一个数组 Array。
type: 'tree',
smooth: true, // 各个树节点的连接线是否是平滑的曲线
line: {
  stroke: 'red', // 连接边的颜色
  lineWidth: 1 // 连接边的粗细
} // 连接各个树节点的线的配置项
}

mirror 镜像分面

facet: {
field: {Array}, // 用于切割分面的数据源字段，是一个数组 Array。
type: 'mirror',
transpose: true // 设置镜像是否反转，默认为 false，不翻转， true 则翻转
}

geoms

类型：Array

用于声明绘制图表的图形语法，可同时声明多种 geom 配置。对应函数式调用 api： Geom。

geoms: [
  {
    type: {String}, // 声明 geom 的类型：point line path area interval polygon schema edge heatmap contour pointStack pointJitter pointDodge intervalStack intervalDodge intervalSymmetric areaStack schemaDodge
  adjusts: {String} || {Array}, // 数据调整方式声明，如果只有一种调整方式，可以直接声明字符串，如果有多种混合方式，则以数组格式传入
  position: {String} || {Object}, // potision 图形属性配置
  color: {String} || {Object}, // color 图形属性配置
  shape: {String} || {Object}, // shape 图形属性配置
  size: {String} || {Object}, // size 图形属性配置
  opacity: {String} || {Object}, // opacity 图形属性配置
  label: {String} || {Object}, // 图形上文本标记的配置
  tooltip: {String}, // 配置 tooltip 上显示的字段名称
    style: {Object}, // 图形的样式属性配置
    selected: {Object}, // geom 选中交互配置
    animate: {Object} // 动画配置
  },
  {
    // 同上述配置相同，可以定义多个 geom
  }
]

positon

用于声明映射至位置 position 属性的数据字段，使用方式很简单：

position: 'field1*field2'

或者

position: {
  field: 'field1*field2'
}

函数式声明 API: position。

color

chart.geom().color(value) 对应：

color: value, // value 可以是数据字段名、颜色值以及包含统计函数的声明

或者

color: {
  field: value, // value 可以是数据字段名、颜色值以及包含统计函数的声明
}

chart.geom().color(dim, colors) 对应：

color: {
  field: ${field}, // 声明映射至 color 属性的数据字段名
  colors: ${colors} // String | Array，可声明颜色、渐变颜色等
}

回调函数声明 chart.geom().color(dim, colorCallback) 对应：

color: {
  field: ${field}, // 声明映射至 color 属性的数据字段名
  callback: {Function} // 用户自定义回调函数
}

函数式声明 API: color。

shape

chart.geom().shape(value) 对应：

shape: value, // value 可以是数据字段名、图形形状名以及包含统计函数的声明

或者

shape: {
  field: value, // value 可以是数据字段名、图形形状名以及包含统计函数的声明
}

chart.geom().shape(dim, shapes) 对应：

shape: {
  field: ${field}, // 声明映射至 shape 属性的数据字段名
  shapes: ${shapes} // String | Array
}

回调函数声明 chart.geom().shape(dim, callback) 对应：

shape: {
  field: ${field}, // 声明映射至 shape 属性的数据字段名
  callback: {Function} // 用户自定义回调函数
}

函数式声明 API: shape。

size

chart.geom().size(value） 对应

size: value // value 可以是数据字段名、数值以及包含统计函数的声明

或者

size: {
  field: value, // value 可以是数据字段名、图形形状名以及包含统计函数的声明
}

chart.geom().size(dim, max, min) 对应：

size: {
  field: {String}, // 声明映射至 size 属性的数据字段名
  min: {Number},
  max: {Number}
}

chart.geom().size(dim, callback) 对应：

size: {
  field: {String}, // 声明映射至 size 属性的数据字段名
  callback: {Function}
}

函数式声明 API: size。

opacity

chart.geom().opacity(dim) 对应：

opacity: dim, // dim 对应映射至 opacity 的数据字段名、具体透明度数值或者包含统计的声明

或者

opacity: {
  field: dim // dim 对应映射至 opacity 的数据字段名、具体透明度数值或者包含统计的声明
}

chart.geom().opacity(dim, callback) 对应

opacity: {
  field: {String}, // 声明映射至 opacity 属性的数据字段名
  callback: {Function}
}

函数式声明 API: opacity。

label

chart.geom().label(dim) 对应

label: dim, // dim 对应字段名或者带有统计的声明

chart.geom().label(dim, cfg) 对应

label: {
  field: {String}, // 需要标注的数据字段名
  cfg: {Object} // 具体的 label 配置，参见https://antv.alipay.com/g2/api/geom.html#label
}

如果 label 中需要声明回调函数，声明 callback 属性即可：

label: {
  field: {String}, // 需要标注的数据字段名
  cfg: {Object}, // 具体的 label 配置
  callback: {Function}
}

函数式声明 API: label。

tooltip: {String} // 直接声明需要显示在 tooltip 上的字段名

函数式声明 API: tooltip。

style

style: {
  // 图形属性声明
}

函数式声明 API: style。

selected

selected: {Boolean} // 开启关闭选中功能

selected: {
  mode:  'multiple' || 'single' || false, // multiple 为多选，single 为单选， false 为关闭选中功能
  style: {
    // 设置选中图形的样式，不设置则使用默认提供的样式
    // 图形绘制属性，如 fill stroke
  }
}

函数式声明 API: selected。

animate

animate: {
  // TODO
  // 同 ...
}

函数式声明 API: animate。

View 视图的配置项声明

视图的配置项同 chart 基本一致，除了不支持 facet，以及 tooltip 属性值为 Boolean 类型外，其他均同 chart 一致。

var view = chart.createView({
  options: {
    appendFields: {Array}, // 作为附加字段，用于补全数据源中的数据字段，常用于数据源含有不同数据字段的记录
    scales: {Object}, // 列定义声明
    coord: {Object}, // 坐标系配置
    axes: {Object}, // 坐标轴配置
    legends: {Object}, // 图例配置
    guides: {Array}, // 图表辅助元素配置
    filters: {Object}, // 数据过滤配置
    tooltip: {Boolean}, // 默认值为 true，显示 tooltip， false 为关闭 tooltip
    geoms: {Array}, // 图形语法相关配置
  }
});