百度图表库标准（1.0）

简介

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

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

编撰

林志峰、赵庶、erik、刘阳、杨冬

本文档由百度Flash组与商业运营体系前端技术组联合审校发布。

要求

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

名词解析

基本名词

图表名词

图表类型

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

line

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

bar

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

scatter

散点图	气泡图

pie

饼图	圆环图

radar

雷达图	填充雷达图

初始化

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

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

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

方法

选项

option

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

legend

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

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

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

内容格式器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触发

grid

直角坐标系内绘图网格

xAxis

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

yAxis

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

axis

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

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

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

boundaryGap端空白策略

设置	效果
boundaryGap: true
boundaryGap: false

axis属性说明

axis.axisLabel

坐标轴文本标签选项

间隔名称格式器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

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

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属性为对象，其包含：

其中饼图标签label属性为对象，其包含：

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

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

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

lineStyle

线条（线段）样式

areaStyle

区域填充样式

textStyle

文字样式

loadingOption

过渡显示，loading（读取中）的选项

多级控制设计

简单的说，你可以通过这三级满足不同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();