百度图表库编程标准

发布于 2020-12-12 09:59:02 字数 25299 浏览 988 评论 0

图表在各种类型的产品中都有应用,本文档主要的设计目标是规范前端图表库的标准图表类型、接口、数据格式及样式设置,使之容易被理解、使用和维护。

同时,希望通过这次标准化,推动创建出可用的标准图表库,使之能更快捷地应用到各个项目中。

要求

在本文档中,使用的关键字会以中文+括号包含的关键字英文表示: 必须(MUST) 。关键字"MUST", “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and "OPTIONAL"被定义在rfc2119中。

名词解析

基本名词

名词描述
chart是指一个完整的图表,如折线图,饼图等“基本”图表类型或由基本图表组合而成的“混搭”图表,可能包括坐标轴、图例等
axis直角坐标系中的一个坐标轴,坐标轴可分为类目轴和数值轴
xAxis直角坐标系中的横轴,通常并默认为类目轴
yAxis直角坐标系中的纵轴,通常并默认为数值轴
grid直角坐标系中除坐标轴外的绘图网格
tooltip提示框
legend图例
series数据系列

图表名词

名词描述
line折线图,堆积折线图,面积图,堆积面积图
bar柱形图,堆积柱形图,条形图,堆积条形图
scatter散点图,气泡图
pie饼图,圆环图
radar雷达图,填充雷达图

图表类型

图表库标准包含单图表类型的标准图表以及多图表类型混合的混搭图表:

标准图表类型

line

折线图堆积折线图面积图堆积面积图
折线图堆积折线图面积图堆积面积图

bar

柱形图堆积柱形图条形图堆积条形图
柱形图堆积柱形图条形图堆积条形图

scatter

散点图气泡图
散点图气泡图

pie

饼图圆环图
饼图圆环图

radar

雷达图填充雷达图
雷达图填充雷达图

初始化

图表库实现 必须(MUST) 为多实例的,实例选项 应当(SHOULD) 在新建时传入,同时 可选(OPTIONAL) 的在实例新建后通过实例方法setOption(见方法)传入,两种初始化方式最终产出效果 必须(MUST) 是等价的,即如下两组代码产出效果相同。

//初始化实例时传入选项
var myChart = new echarts(option);

//初始化实例选项为空,通过实例方法传入选项
var myChart = new echarts();
myChart.setOption(option);

同时,在实例中任何个性化选项 不得(MUST NOT) 影响其他已存在或未来生成的实例。

方法

名称描述
{void} setOption( {Object} option )万能接口,配置图表实例任何可配置选项(详见 option ),多次调用时option选项 *必须(MUST)* 是合并(merge)的
{void} setSeries( {Array} series )数据接口,驱动图表生成的数据内容(详见 series ),效果 *应当(SHOULD)* 等同调用setOption({series:{...}})
{void} on( {string} eventName, {Function} eventListener )事件绑定, *必须(MUST)* 支持事件有:click,hover
{void} un( {string} eventName, {Function} eventListener )事件解绑定
{void} showLoading( {Object} loadingOption)过渡控制(详见 loadingOption ),显示loading(读取中)
{void} hideLoading( {void} )过渡控制,隐藏loading(读取中)
{void} clear( {void} )清空绘画内容,清空后实例可用
{void} dispose( {void} )释放图表实例,释放后实例不再可用

选项

option

图表选项,包含图表实例任何可配置选项

名称描述
{Array} color数值系列的颜色列表,默认为null则采用内置颜色,可配数组,eg:['#87cefa', 'rgba(123,123,123,0.5)','...'],当系列数量个数比颜色列表长度大时将循环选取
{Object} legend图例(详见 legend ),每个图表最多仅有一个图例,混搭图表共享
{Object} tooltip提示框(详见 tooltip ),鼠标悬浮交互时的信息提示
{Object} grid直角坐标系内绘图网格(详见 grid )
{Array} xAxis直角坐标系中横轴数组(详见 xAxis ),数组中每一项代表一条横轴坐标轴,标准(1.0)中规定最多同时存在2条横轴
{Array} yAxis直角坐标系中纵轴数组(详见 yAxis ),数组中每一项代表一条纵轴坐标轴,标准(1.0)中规定最多同时存在2条纵轴
{Array} series驱动图表生成的数据内容(详见 series ),数组中每一项代表一个系列的特殊选项及数据

legend

图例,每个图表最多仅有一个图例

  <tr>
    <td> {string} itemRender </td>
    <td> null </td>
    <td> 默认item渲染器(详见 <a href="#Series">series</a> 中itemRender描述) </td>
  </tr>
  <tr>
    <td> {Object} itemStyle </td>
    <td> null </td>
    <td> 默认item渲染样式(详见 <a href="#Series">series</a> 中itemStyle描述) </td>
  </tr>
  <tr>
    <td> {Array} data </td>
    <td> null </td>
    <td> 图例内容(详见 <a href="#LegendData">legend.data</a> ,数组中每一项代表一个item </td>
  </tr>
</tbody>
名称默认值描述
{string} orient'horizontal'布局方式,默认为水平布局,可选为:'horizontal' ¦ 'vertical'
{string} ¦ {number} x'center'水平安放位置,默认为全图居中,可选为:'center' ¦ 'left' ¦ 'right' ¦ {number}(x坐标,单位px)
{string} ¦ {number} y'top'垂直安放位置,默认为全图顶端,可选为:'top' ¦ 'bottom' ¦ 'center' ¦ {number}(y坐标,单位px)
{string} backgroundColor'#fff'图例背景颜色
{string} borderColor'#333'图例边框颜色
{number} borderRadius4图例边框圆角,单位px,默认为4
{number} borderWidth0图例边框线宽,单位px,默认为0(无边框)
{number} ¦ {Array} padding5图例内边距,单位px,默认各方向内边距为5,接受数组分别设定上右下左边距,同css
{number} itemGap10各个item之间的间隔,单位px,默认为10,横向布局时为水平间隔,纵向布局时为纵向间隔

图例

legend.data

图例内容数组,数组中每一项代表一个item,数组项可为{Object},可以完整指定一个图例item的内容:

[
  {
    name:'xxx',             //图例名称
    itemRender:'yyy',         //item渲染器,详见series中itemRender描述
    itemStyle:{...}           //item渲染样式,详见series中itemStyle描述
  }
  /*,{...}*/
]

当不指定itemRender或itemStyle时,则会根据name值索引series中同名name所用的itemRender或itemStyle,如果上述两项都不指定则数组项可退化为{string},即

[
  {
    name:'xxx'
  },
  {
    name:'zzz'
  }
]

['xxx','zzz']

是等价的。

当不指定itemRender或itemStyle,同时根据name值索引不到series中有同名name时,则会使用legend中itemRender或itemStyle,如果此时legend.itemRender或legend.itemStyle不存在则该项图例item将不被显示

tooltip

提示框,鼠标悬浮交互时的信息提示

名称默认值描述
{string} trigger'item'触发类型,默认数据触发,见下图,可选为:'item' ¦ 'axis'
{boolean} showtrue显示策略,可选为:true(显示) ¦ false(隐藏)
{string} ¦ {Function} formatternull内容格式器:{string}(Template) ¦ {Function},见表格下方
{string} backgroundColor'rgba(0,0,0,0.7)'提示背景颜色,默认为透明度为0.7的黑色
{string} borderColor'#333'提示边框颜色
{number} borderRadius4提示边框圆角,单位px,默认为4
{number} borderWidth0提示边框线宽,单位px,默认为0(无边框)
{number} ¦ {Array} padding5提示内边距,单位px,默认各方向内边距为5,接受数组分别设定上右下左边距,同css
{Object} textStylenull文本样式(详见 textStyle )

内容格式器formatter:

  • {string},模板(Template),其变量为:
    • {a} ¦ {a0}
    • {b} ¦ {b0}
    • {c} ¦ {c0}
    • {d} ¦ {d0} (部分图表类型无此项)
    • 多值下则存在多套{a1}, {b1}, {c1}, {d1}, {a2}, {b2}, {c2}, {d2}, …
    • 其中变量a、b、c在不同图表类型下代表数据含义为:
      • 折线(面积)图、柱状(条形)图、散点图 : a(系列名称),b(横轴值),c(纵轴值), d(无)
      • 气泡图 : a(系列名称),b(横轴值),c(纵轴值), d(数值)
      • 饼图、雷达图 : a(系列名称),b(数据项名称),c(数值), d(百分比)
  • {Function},传递参数为数组,数组项同模板变量:
    • [[a, b, c, d], [a1, b1, c1, d1], …]

触发类型

item触发axis触发
item触发axis触发

grid

直角坐标系内绘图网格

名称默认值描述
{number} x80直角坐标系内绘图网格起始横坐标,数值单位px
{number} y40直角坐标系内绘图网格起始纵坐标,数值单位px
{number} width600直角坐标系内绘图网格宽度,数值单位px
{number} height250直角坐标系内绘图网格高度,数值单位px

绘图网格

xAxis

直角坐标系中横轴数组,数组中每一项代表一条横轴坐标轴。
标准(1.0)中规定最多同时存在2条横轴,单条横轴时可指定安放于grid的底部(默认)或顶部,2条同时存在时则默认第一条安放于底部,第二天安放于顶部。
坐标轴有两种类型,类目型和数值型(区别详见axis),横轴通常为类目型,但条形图时则横轴为数值型,散点图时则横纵均为数值型,具体参数详见axis。

yAxis

直角坐标系中纵轴数组,数组中每一项代表一条纵轴坐标轴。
标准(1.0)中规定最多同时存在2条纵轴,单条纵轴时可指定安放于grid的左侧(默认)或右侧,2条同时存在时则默认第一条安放于左侧,第二天安放于右侧。
坐标轴有两种类型,类目型和数值型(区别详见axis),纵轴通常为数值型,但条形图时则纵轴为类目型,具体参数详见axis。

axis

坐标轴有两种类型,类目型和数值型,他们的区别在于:

  • 类目型:需要指定类目列表,坐标轴内有且仅有这些指定类目坐标
  • 数值型:需要指定数值区间,坐标轴内包含数值区间内容全部坐标

下面是坐标轴的全部选项,其中个别选项仅在类目型或数值型时有效,请注意适用类型:

名称默认值适用类型描述
{string} type'category' ¦ 'value'通用坐标轴类型,横轴默认为类目型'category',纵轴默认为数值型'value'
{string} position'bottom' ¦ 'left'通用坐标轴类型,横轴默认为类目型'bottom',纵轴默认为数值型'left',可选为:'bottom' ¦ 'top' ¦ 'left' ¦ 'right'
{boolean} boundaryGaptrue类目型类目起始和结束两端空白策略,见下图,默认为true留空,false则顶头
{Array} boundaryGap[0, 0]数值型数值轴两端空白策略,数组内数值代表百分比,[原始数据最小值与最终最小值之间的差额,原始数据最大值与最终最大值之间的差额]
{number} minnull数值型指定的最小值,eg: 0,默认无,会自动根据具体数值调整,指定后将忽略boundaryGap[0]
{number} maxnull数值型指定的最大值,eg: 100,默认无,会自动根据具体数值调整,指定后将忽略boundaryGap[1]
{number} precision0数值型小数精度,默认为0,无小数点
{number} power100数值型整数精度,默认为100,个位和百位为0
{number} splitNumber5数值型分割段数,默认为5
{Object} axisLine{show : true}通用坐标轴线,默认显示,属性show控制显示与否,属性lineStyle(详见 lineStyle )控制线条样式
{Object} axisTick{show : false}通用坐标轴小标记,默认不显示,属性show控制显示与否,属性length控制线长,属性lineStyle(详见 lineStyle )控制线条样式
{Object} axisLabel{show : true}通用坐标轴文本标签,详见 axis.axisLabel
{Object} splitLine{show : true}通用分隔线,默认显示,属性show控制显示与否,属性lineStyle(详见 lineStyle )控制线条样式
{Object} splitArea{show : false}通用分隔区域,默认不显示,属性show控制显示与否,属性areaStyle(详见 areaStyle )控制区域样式
{Array} data[]类目型类目列表,同时也是label内容,详见 axis.data

boundaryGap端空白策略

设置效果
boundaryGap: trueaxisBoundaryGap1
boundaryGap: falseaxisBoundaryGap

axis属性说明

axisDetail

axis.axisLabel

坐标轴文本标签选项

名称默认值适用类型描述
{boolean} showtrue通用是否显示,默认为true,设为false后下面都没意义了
{string} ¦ {number} interval'auto'类目型标签显示挑选间隔,默认为'auto',可选为:'auto'(自动隐藏显示不下的) ¦ 0(全部显示) ¦ {number}(用户指定选择间隔)
{number} rotate0通用标签旋转角度,默认为0,不旋转,正直为逆时针,负值为顺时针,可选为:-90 ~ 90
{number} margin2通用坐标轴文本标签与坐标轴的间距,默认为2
{string} ¦ {Function} formatternull通用间隔名称格式器:{string}(Template) ¦ {Function}
{Object} textStylenull通用文本样式(详见 textStyle )

间隔名称格式器formatter:

  • {string},模板(Template),其变量为:
    • {value}: 内容或值
  • {Function},传递参数同模板变量:
    • eg:function(value){return “星期” + “日一二三四五六”.charAt(value);’}

axis.data

类目型坐标轴文本标签数组,指定label内容。
数组项通常为文本,如:

['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', ..., 'Dec']

当需要对个别标签进行个性化定义时,数组项可用对象,如:

[
  'Jav', 'Feb', 'Mar',
   {
    value:'Apr',      //文本内容,如指定间隔名称格式器formatter,则这个值将被作为模板变量值或参数传入
    textStyle:{       //详见textStyle
      color : 'red'
      ...     
    }
   },
  'May', '...'
] 

series

驱动图表生成的数据内容,数组中每一项代表一个系列的特殊选项及数据,其中个别选项仅在部分图表类型中有效,请注意适用类型:

名称默认值适用类型描述
{string} name''通用系列名称
{Object} tooltipnull通用提示框样式,仅对本系列有效,如不设则用option.tooltip(详见 tooltip ),鼠标悬浮交互时的信息提示
{string} type'line'通用图表类型,必要参数!可选为:折线图'line' ¦ 散点图'scatter' ¦ 柱状图'bar' ¦ 饼图'pie' ¦ 雷达图'radar'
{string} itemRendernull通用图形项渲染器
{Object} itemStylenull通用图形样式(详见 itemStyle )
{string} stacknull折线图,柱状图,散点图组合名称,做多组数据的堆积图时使用,eg:stack:'group1',则series数组中stack值等于'group1'的数据做堆积计算
{number} xAxisIndex0折线图,柱状图,散点图xAxis 坐标轴数组的索引,指定该系列数据所用的横坐标轴
{number} yAxisIndex0折线图,柱状图,散点图yAxis 坐标轴数组的索引,指定该系列数据所用的纵坐标轴
{number} barMinHeight20柱状图柱条最小高度,防止某item的值过小而影响交互
{number} barWidth40柱状图柱条宽度
{Array} centernull饼图圆心坐标,默认无(为自适应居中)
{number} ¦ {Array} radius100饼图半径,传数组实现环形图,[内半径,外半径]
{number} startAngle0饼图开始角度,
{number} minAngle5饼图最小角度,避免显示过小
{Array} data[]通用数据(详见 series.data )

series.data

系列中的内容数组,折线图以及柱状图中当前数组长度 必须(MUST) 等于所使用类目轴文本标签数组axis.data的长度,并且他们间是一一对应的,。
数组项通常为数值,如:

[12, 34, 56, ..., 10, 23]

当某类目对应数据不存在(‘不存在’ != 0)时,可用’-'表示,无数据在折线图中表现为折线在该点断开,在柱状图中表现为该点无柱形,如:

[12, '-', 56, ..., 10, 23]

当需要对个别内容进行个性化定义时,数组项可用对象,如:

[
  12, 34,
  {
    value : 56,     
    tooltip:{},       //自定义特殊tooltip,仅对该item有效,详见tooltip
    itemRender:{},    //自定义特殊itemRender,仅对该item有效,同itemRender
    itemStyle:{}      //自定义特殊itemStyle,仅对该item有效,详见itemStyle
  },
  ..., 10, 23
] 

特别的,当图表类型为scatter(散点图或气泡图)时,其数值设置比较特殊,他的横纵坐标轴都可能为数值型,并且气泡图时需要指定气泡大小,所以scatter型图表 应当(SHOULD) 设置为:

[
  {
    value : [10, 25, 5]   //[xValue, yValue, rValue],数组内依次为横值,纵值,大小
  },
  ...,
  {
    value : [30, 128, 15],  //同上    
    tooltip:{},       //自定义特殊tooltip,仅对该item有效,详见tooltip
    itemRender:{},      //自定义特殊itemRender,仅对该item有效,同itemRender
    itemStyle:{}      //自定义特殊itemStyle,仅对该item有效,详见itemStyle
  }
] 

再特别的,当图表类型为饼图时,需要说明每部分数据的名称name,所以 应当(SHOULD) 设置为:

[
  {
    value : 12,
    name : 'apple'      //每部分数据的名称
  },
  ...,
  {
    value : 23,       //同上
    name : 'orange'     //同上    
    tooltip:{},       //自定义特殊tooltip,仅对该item有效,详见tooltip
    itemRender:{},      //自定义特殊itemRender,仅对该item有效,同itemRender
    itemStyle:{}      //自定义特殊itemStyle,仅对该item有效,详见itemStyle
  }
] 

itemStyle

图形样式,可设置图表内图形的默认样式和强调样式(悬浮悬浮时样式):

itemStyle: { 
  normal: {
    ...
  },
  emphasis: {
    ...
  } 
}

其中normal和emphasis属性为对象,其包含:

名称默认值适用类型描述
{string} color图表各异通用颜色
{Object} lineStyle图表各异折线图线条样式,详见 lineStyle
{Object} areaStyle图表各异堆积折线图,柱状图,饼图,填充雷达图区域样式,详见 areaStyle
{Object} label{show: true, position:'outer'}饼图饼图标签,默认悬浮时显示
{Object} labelLine{show: true}饼图饼图标签视觉引导线,当饼图标签位置(label.position)为'outer'时有效

其中饼图标签label属性为对象,其包含:

名称默认值描述
{boolean} showtrue标签显示策略,可选为:true(显示) ¦ false(隐藏)
{string} position'outer'标签显示位置,可选为:'outer'(外部) ¦ 'inner'(内部)
{Object} textStylenull标签的文本样式(详见 textStyle )

其中饼图标签视觉引导线labelLine属性为对象,其包含:

名称默认值描述
{boolean} showtrue饼图标签视觉引导线显示策略,可选为:true(显示) ¦ false(隐藏)
{number} length50线长
{Object} lineStyle各异线条样式,详见 lineStyle

通过有效设置itemStyle的normal和emphasis选项可实现个性化的显示策略,比如希望饼图文字标签默认隐藏,并在鼠标悬浮时通过一条红色的视觉引导线显示在饼图外部区域,可以如下设置:

itemStyle: { 
  normal: {
    label: {
      show: false
    }
    labelLine: {
      show: false
    }       
  } ,
  emphasis: {
    label: {
      show: true,
      position: 'outer'
    }
    labelLine: {
      show: true,
      lineStyle: {
        color: 'red'
      }
    }
  } 
}

lineStyle

线条(线段)样式

名称描述
{string} color颜色
{string} type线条样式,可选为:'solid' ¦ 'dotted' ¦ 'dashed'
{number} width线宽

areaStyle

区域填充样式

名称描述
{string} color颜色
{string} type填充样式,标准(1.0)目前仅支持'default'(实填充)

textStyle

文字样式

名称描述
{string} color颜色
{string} decoration修饰,可选为:'none' ¦ 'underline'
{string} align对齐方式,可选为:'left' ¦ 'right' ¦ 'center' ¦ 'justify'
{string} fontFamily字体系列
{string} fontSize字号
{string} fontStyle样式,可选为:'normal' ¦ 'italic'
{string} fontWeight粗细,可选为:'normal' ¦ 'bold' ¦ 'bolder' ¦ 'lighter'

loadingOption

过渡显示,loading(读取中)的选项

名称默认值描述
{string} text''显示话术
{string} ¦ {number} x'center'水平安放位置,默认为全图居中,可选为:'center' ¦ 'left' ¦ 'right' ¦ {number}(x坐标,单位px)
{string} ¦ {number} y'center'垂直安放位置,默认为全图居中,可选为:'center' ¦ 'bottom' ¦ 'top' ¦ {number}(y坐标,单位px)
{Object} textStylenull显示话术的文本样式(详见 textStyle )

多级控制设计

简单的说,你可以通过这三级满足不同level的定制和个性化需求:

  • 通过 option.* 设置全局统一配置;
  • 通过 option.series.* 设置特定系列特殊配置,其优先级高于 option 内的同名配置;
  • 通过 option.series.data.* 设置特定数据项的特殊配置,最高优先级;

多级控制

附录:一个直观的事例

// 图表实例化------------------
var myChart = new echarts();

// 图表使用-------------------
var option = {
  // 图例配置
  legend: {
    padding: 5,               // 图例内边距,单位px,默认上下左右内边距为5
    itemGap: 10,              // Legend各个item之间的间隔,横向布局时为水平间隔,纵向布局时为纵向间隔
    data: ['ios', 'android']
  },
  
  // 气泡提示配置
  tooltip: {
    trigger: 'item',            // 触发类型,默认数据触发,可选为:'axis'
  },
  
  // 直角坐标系内绘图网格
  grid: {           
    width: 500,               // 直角坐标系内绘图网格宽度,数值单位px,并不包括坐标label
    height: 300               // 直角坐标系内绘图网格高度,数值单位px,并不包括坐标label
  },
  
  // 直角坐标系中横轴数组
  xAxis: [
    {
      type: 'category',           // 坐标轴类型,横轴默认为类目轴,数值轴则参考yAxis说明
      data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']     
    }
  ],
  
  // 直角坐标系中纵轴数组
  yAxis: [
    {
      type: 'value',            // 坐标轴类型,纵轴默认为数值轴,类目轴则参考xAxis说明
      boundaryGap: [0.1, 0.1],      // 坐标轴两端空白策略,数组内数值代表百分比
      splitNumber: 4            // 数值轴用,分割段数,默认为5
    }
  ]         
};
myChart.setOption(option);

//ajax getting data...............

// 过渡---------------------
myChart.showLoading({
  text: '正在努力的读取数据中...',  //loading话术
  x: 'center',            //水平安放位置,默认为 'center',可选为:'left' || 'right' || Number可指定x坐标
  y: 'center'             //垂直安放位置,默认为'center',可选为: 'top' || bottom' || Number可指定y坐标
});

//ajax return
myChart.hideLoading();

// 数据数组,data from ajax
var series = [
  {
    name: 'ios',              // 系列名称
    type: 'line',               // 图表类型,折线图line、散点图scatter、柱状图bar、饼图pie、雷达图radar
    data: [112, 23, 45, 56, 233, 343, 454, 89, 343, 123, 45, 123]
  },
  {
    name: 'android',            // 系列名称
    type: 'line',               // 图表类型,折线图line、散点图scatter、柱状图bar、饼图pie、雷达图radar
    data: [45, 123, 145, 526, 233, 343, 44, 829, 33, 123, 45, 13]
  }
];

myChart.setSeries(series);

// 图表清空-------------------
myChart.clear();

// 图表释放-------------------
myChart.dispose(); 

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

列表为空,暂无数据

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

0 文章
0 评论
84935 人气
更多

推荐作者

待"谢繁草

文章 0 评论 0

战皆罪

文章 0 评论 0

子英

文章 0 评论 0

爱的十字路口

文章 0 评论 0

孤者何惧

文章 0 评论 0

xi霄xi

文章 0 评论 0

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击“接受”或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。