flot中文说明文档 简版

Flot参考文档：

一．对绘图函数plot的调用：var plot=$.plot(placeholder,data,options)

-----------

placeholder

-----------

占位符placeholder是一个jQuery对象或者DOM元素或者jQuery表单式，绘图函数将把图表画在placeholder内。

这个占位符要事先设置宽，高。

plot函数画图时将修改这个占位符的内容，因此你最好使用一个空的DIV元素作为占位符，另外注意不要给占位符设置花哨的样式，比如，在IE7.0下，给占位符设置背景图将会出错。

 

-----------

data参数

-----------

flot的数据是一个数列数组。

plot函数中的data参数:每条曲线一个data项参数，绘制多条曲线时，是一个数组，每个数组元素是一条曲线的data项参数。

数列可以是原始数据，也可以是数据对象。

1.原始数据

原始数据格式是由一组表示数据点的坐标值的数组构成：[ [x1, y1],[x2, y2], ... ]

请注意，flot的纵横坐标值都必须是数字(即使用时间数列也是，后面会介绍到)。

这是个很常见的错误，因为你很可能从数据库获取数据后没有检查数据类型就直接转化成json对象使用。

如果你觉得遇到了莫名其妙的错误，请确认一下你输入的是数字而不是字符串。

如果坐标为值为空 ,或者其中的一个坐标值为空，或者不是数字，或者说不能转换为数字，那么这个节点将被忽略，并且该节点前后的2个节点之间不会使用直线来连接。

折线图和散点图每个节点有2个参数，直方图则有3个参数，第三个参数来指定直方图的底部位置(缺省值是0)。

2.对象数据

单个图表对象数据格式参数如下：

{

        color: color or number   //颜色

        data: rawdata  //数据

        label: string  //曲线名称

        lines: specific lines options  //折线图坐标参数

        bars: specific bars options   //直方图坐标参数

        points: specific points options  //散点图坐标参数

        xaxis: 1 or 2  //使用哪一条X轴，如果某条数轴没有被任何一条曲线使用，该数轴不会在图表上出现

        yaxis: 1 or 2  //使用哪一条Y轴

        clickable: boolean  //允许监听鼠标点击事件

        hoverable: boolean  //允许监听鼠标悬停事件

        shadowSize: number //曲线阴影

}

一般情况下你无须设置每一个参数， 你只需要设置其中几个特定的参数即可，其他参数会使用默认值。

参数详解：

l  label string 用于指定曲线名称，如果没有设置label的值，图表标题区域不会出现。

l  color 设置曲线颜色如果没有设置曲线颜色，程序会自动采用默认颜色(options项里的colors数列)。颜色值可以是CSS颜色格式(RGB格式、16进制颜色、WEB通用颜色名) 还可以是数字编号，数字编号表示颜色数列里面颜色的编号。

l  如果你允许用户重置或删除曲线，后者会比较有用，你可以在代码里面设置曲线使用的默认颜色的序号防止相同颜色在不用曲线间重复出现。

l  xaxis" 和 "yaxis" 设置曲线使用的数轴(第二条X轴是顶部横轴，第二条Y轴是右边的纵轴)，你可以使用这个属性制作双数轴曲线。

l  "clickable" 和 "hoverable"用于关闭该曲线的鼠标点击效果或鼠标悬停效果，具体说明看后面。

 

其他参数在后面介绍，他们与plot函数的"options"参数的设置项是一样的，如果你为某条曲线在data里面设置了这些参数的值，他们会覆盖掉options的默认值。

 

-----------

option参数

-----------

options的所有选项都是可选的，他们都有默认值，后面会逐条对他们进行讲解，如果要修改这些选项的默认值你只需要明确指定他们的值即可。

相关参数：

1.  legend：定制曲线图表标题

legend 用于生成图表标题，图表标题以表格的方式显示在曲线图上。

格式：

legend: {

        show: boolean

        labelFormatter:null or (fn: string, series object -> string)

        labelBoxBorderColor: color

        noColumns: number

        position: "ne" or"nw" or "se" or "sw"

        margin: number of pixels or [x margin,y margin]

        backgroundColor: null or color

        backgroundOpacity: number between 0 and1

        container: null or jQuery object/DOMelement/jQuery expression

  }

参数详解：

l  labelFormatter：定制图表标题的格式。

如果你想定制图表标题的格式，比如做成超链接，你可以在"labelFormatter"项使用函数来定制。

例：

  labelFormatter: function(label, series) {

    //series是名称为label的曲线的数据对象

    return '<a href="#' + label +'">' + label + '</a>';

  }

l  noColumns：用于设置表格的列数。

l  position：用于指定legend在曲线图内的位置，"ne"东北角，"se"东南 , "nw"西北 , "sw"西南。

l  margin： 设置legend与曲线图边框的距离,可以是x y轴偏移量的数值对[x,y]。也可以是单个数字，单个数字值表示相对x,y轴的偏移量使用相同的值。

采用哪条X轴和Y轴作为参照物取决于position的值。

l  backgroundColor： 设置legend的背景颜色。

l  backgroundOpacity： 设置legend背景的透明度。

l  container：如果你想把legend放在其他DOM元素内，可以为container设定一个值。

container的值可以是jQuery对象或表达式，例如：container: $("#showChartLegend")。

container为legend指定容器后，"position" 和 "margin" 等与图表相关的位置属性会被忽略，

另外请注意，container指定的容器内容会被覆盖掉。

2.  xaxis, yaxis, x2axis, y2axis数轴定制

格式：

xaxis,yaxis, x2axis, y2axis: {

mode: nullor "time"  //数轴是否为时间模式

min: null ornumber  //数轴最小值

max: null ornumber  //数轴最大值

autoscaleMargin:null or number  //见参数详解

labelWidth:null or number

labelHeight:null or number

transform:null or fn: number -> number

inverseTransform:null or fn: number -> number

ticks: nullor number or ticks array or (fn: range -> ticks array)

tickSize:number or array

minTickSize:number or array

tickFormatter:(fn: number, object -> string) or string

tickDecimals:null or number

}

参数详解：

l  mode 数轴样式，mode为null表示数轴十进制，为time设置为时间轴。

l  min/max 设置数轴最大值和最小值，如果没有明确指定他们，将自动使用数据中的最小值和最大值。

l  labelWidth/ labelHeight  用于设置数轴刻度标签的高宽，这个属性在你需要排列整齐几个图表的时候会派上用场。

l  transform/ inverseTransform  为回调函数  用于改变数轴上的数据显示方式。你可以设计一个函数来非线性地扩展或压缩数轴上的特定数据段。

例：

xaxis: {

                transform: function (v) {return Math.log(v); },

                inverseTransform: function (v){ return Math.exp(v); }

 }

需要注意的是，flot假定transform函数不会修改数据点的排列顺序。

inverseTransform 函数是对transform的逆运算，因此有：

v == inverseTransform(transform(v)

当需要把坐标数据转换回数值数据时就会用到这个函数，这常在图表的动态交互时发生，比如鼠标在图标上面点击并获取该点数据，但是如果你不做任何动态的交互，你可能不会用到这个函数。

        其他与刻度网格相关的参数：

如果你没有明确地设置刻度间隔，程序会自动设置，设置过程分为2步，

首先估计数轴刻度间隔所需数目，其次根据这个数目通过四舍五入方法估算合适的步长，最后生成刻度。

l  ticks  通过设置"ticks" 的值为数字，你可以设置图表产生刻度间隔的个数，但是程序尽量会设置最合适的刻度个数，因此，尽管你设置了3个刻度数，却可能得到5个，如果你不需要自己设置刻度，把"ticks"的值设置为0或一个空数组。

l  tickSize 直接跳过估算步骤设置刻度间隔步长，如果你设置该值为2，生成的刻度将会是形如2，4，6。

l  minTickSize 可以设置刻度间隔的最小值。

如果你想完全的自定义刻度，可以设置参数"ticks"的值为一个数组，赋值方法如下例：ticks: [0, 1.2, 2.4]。

或者像下面的例子，连刻度的标签也自定义：

ticks: [[0, "zero"], [1.2,"one mark"], [2.4, "two marks"]]。

这两种方法可以混合使用。

刻度可以用函数来生成，方法是把一个函数赋给"ticks"，该函数应该以一个具有最大刻度值及最小刻度值的数轴对象为参数，

该函数返回一个刻度数组赋给"ticks"。

下例是一个简单的刻度生成器，例子以pi值为刻度间隔大小，这对三角函数曲线非常适用。

function piTickGenerator(axis) {

                var res = [], i =Math.floor(axis.min / Math.PI);

                do {

                       var v = i * Math.PI;

                       res.push([v, i +"\u03c0"]);

                       ++i;

                   } while (v < axis.max);

                    return res;

}

l  tickDecimals  用于设置刻度的小数位数，默认情况下程序会自动判断截取。

l  tickFormatter可以通过函数来设置刻度显示格式，格式函数有2个参数，刻度值及数轴对象。函数应该返回一个字符串赋给tickFormatter。

"tickFormatter"格式函数基本格式如下：

             function formatter(val, axis) {

                 returnval.toFixed(axis.tickDecimals);

}

数轴对象可以获取数轴数据的最大值和最小值，tickDecimals可以获取刻度标签的小数位数，tickSize可以获取刻度间隔长度(程序算法自动计算出或自定义)。

3.  数据显示定制

格式：

series: {

           lines, points, bars: {

               show: boolean

               lineWidth: number

               fill: boolean or number

               fillColor: null or color/gradient

}

 

           points: {

               radius: number

}

 

           bars: {

               barWidth: number

               align: "left" or "center"

               horizontal: boolean

}

 

           lines: {

               steps: boolean

}

 

           shadowSize: number

      }

 

     colors: [ color1, color2, ... ]

 

    参数详情：

l  series: {} "series: {}"内的参数将对每一个数据序列生效，可以用来为图表设置全局参数，如果需要为特定数据序列的图表设置不同属性，可以在对应的数据序列对象里面设置相应的参数把全局参数覆盖掉。

l  lines/ points/ bars  是最重要的参数，这些参数设置每条数据序列的图表的折线图、散点图、直方图是否显示和如何显示。

如果没有专门设置这三个参数中的任何一个，默认情况下将显示折线图，关闭折线图的方法是lines: { show: false}。

l  lineWidth 用于设置折线图线条的粗细或其他图型的边框，你可以把这个值设置成0来关闭折线图的输出用于设置折线图线条的粗细或其他图型的边框，你可以把这个值设置成0来关闭折线图的输出。

l  fill  用于设置图表填充的透明度(0-1)，对于折线，填充范围是折线与数轴围成的区域。

l  fillColor 设置填充颜色，如果填null,将使用线条颜色一致的颜色，如果颜色名解析失败将使用默认颜色(折线图直方图黑色，散点图白色)。

l  barWidth 用于设置直方图的宽度，单位是数轴的单位而非像素。

l  align  用于设置数据点对应刻度线与直方图之间的对齐关系，默认情况下，刻度线在直方图的左侧(left,靠近数轴最小值一侧)，如果设置为center，刻度线在直方图中间。

l  step  对于折线图，"steps"可以设置是否使用阶梯状折线，设置为true采用阶梯状折线，相邻2个数据点之间先以水平线连接，后然用垂直线连接，需要注意的是，这种模式会在同一垂直线上增加数据点来实现。

l  shadowSize 可以设置曲线阴影大小，设置为0关闭阴影效果。

l  color "colors"可以预定义一系列颜色保存在数组里供曲线使用，你可以设置任意多种颜色。

如：colors:["#d18b2c", "#dba255", "#919733"]。

4.  背景栅格定制

格式：

grid: {

            show: boolean

            aboveData: boolean

            color: color

            backgroundColor: color/gradient ornull

            tickColor: color

            labelMargin: number

             markings: array of markings or(fn: axes -> array of markings)

            borderWidth: number

            borderColor: color or null

            clickable: boolean

            hoverable: boolean

            autoHighlight: boolean

            mouseActiveRadius: number

 }

参数详解：

l  color  定义的是grid的颜色，包括刻度值标签的颜色。

l  backgroundColor 背景色 填充在grid内部，默认情况下背景是透明的，可以为背景设置颜色渐变，具体细节后面会提到。

l  show  如果grid的"show"参数设置为false，栅格背景包括数轴及数轴刻度标签将被隐藏。

l  aboveData 用于设置栅格放置在数据点上面还是下面，默认情况false是放在数据点下面。

"aboveData"设置为true且设置了背景颜色，曲线将被grid的背景颜色遮盖。

l  tickColor 设置刻度线的颜色。

l  labelMargin 设置刻度值标签与网格的距离。

l  borderWidth 设置边框宽度，设为0则取消边框。

l  borderColor 设置边框颜色。

l  tickLabel 设置刻度值标签的CSS样式，(未实验，设置方法不明)。

l  markings 用于在背景上绘画出一块矩形。

矩形的位置及长宽通过纵横轴的起始终止坐标来确定，第一横轴与第一纵轴对应，第二横轴与第二纵轴对应，color参数可以设置画出区块的颜色，赋值方式是一个数组，每个数组元素是一个json数据格式，每个数组元素绘制一个区块。

可以用函数返回数组来赋值。

下面是个简单例子：

  markings: [ { xaxis: { from: 0, to: 2 },yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]

如果只设置一个数轴的数据范围，则缺省数轴的数据范围默认为[min,max]，如果数轴起止值相等，则画出一条线，并且可以使用"lineWidth"设定线段的大小。

l  clickable 设置为true时，图表将监听鼠标单击事件，单击图表时将触发"plotclick"事件。

回调函数的参数是鼠标坐标和数据点的坐标值，即以像素为单位的位置坐标及以数轴为单位的数据坐标。

如果鼠标点击位置没有数据点，则数据点的参数值是null，反之，是一个json对象。

l  hoverable设置为true将监听鼠标移动事件，鼠标移动到某个位置时发生"plothover"事件，回调函数的参数与"clickable"一致。

"plotclick" 和 "plothover" 事件用法如下：

$("#placeholder").bind("plotclick",function (event, pos, item) {

if (item) {

$("#clickdata").text("Youclicked point " + item.dataIndex + " in " + item.series.label +".");

plot.highlight(item.series,item.datapoint);

}

});

l  autoHighlight "autoHighlight"的值为true，则发生"hoverable"事件和"plotclick"事件时，数据点显示高亮效果，数据点高亮的发生及消失对应有highlight/unhighlight方法。

l  mouseActiveRadius  用来设置可以激活数据点的鼠标与数据点之间的距离，如果在符合距离内有多个数据点，flot会激活最近的数据点，对于直方图，则激活最迟设置的直方图。

 

在某条曲线数据本身设置"hoverable" 和"clickable" 为false则该曲线不会触发事件

但options内设置为false时，不能在某条曲线内通过设置true来开启事件监听功能。

5.  定义变化模式

参数详解：

l  曲线颜色预定义：{ colors: [ color1, color2, ...] }

l  图表栅格背景颜色渐变

grid: {

backgroundColor:{ colors: ["#000", "#999"] }

 }

l  曲线颜色明暗程度及透明度渐变设置，包括开始状态和结束状态的数据：

{ colors: [{opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }

例如：如下例，第一条直方图明度正常，但是后面的逐渐变暗，最后消失。

bars: {

                show: true,

                lineWidth: 0,

                fill: true,

                fillColor:{ colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }

  }

            flot目前只支持从图表top到bottom的垂直渐变，因为IE只能这样实现渐变。

        ----------

        Plot Methods方法

----------

plot函数返回的对象有下面一些方法可供调用：

1. highlight(series,datapoint)  //激活数据点 series：曲线编号，datapoint：数据点在曲线数据序列中的编号，编号都是从0开始 例如：highlight(1, 1) 激活第二条曲线的第二个数据点

                                  //datapoint 也可以是一个数据点的真实数据对象，是一个数组， 例如：highlight(1, [3,6]) 激活第二条曲线上坐标为[3,6]的点

                                  //如果指定坐标的数据点不在该曲线上，仍然以该曲线的颜色显示要激活的数据点

2. unhighlight(series,datapoint) or unhighlight() //取消数据点的激活效果,参数与highlight相同

//如果unhighlight()没有设置参数，取消所有数据点的激活状态

3. setData(data) 

重新设置曲线数据，参数data是plot(placeholder, data, options)中的data参数，可以不包含options的设置内容。

   重新设置数据后，如果需要立即改变图表显示，请调用draw()方法来重新绘制图表

  请注意，setData()方法并不会重新设置数轴的缩放比例、刻度、曲线名称等，如果需要修改这些属性，请使用setupGrid()方法。

如果你预先知道重新设置数据后数轴不需要改变，可以用setData(data)来设置数据然后调用draw()快速重绘曲线

如果数据量比较大，draw()方法可能会消耗较长时间，因此可能会有一点延迟，请不必感到疑惑。

4. setupGrid()  修改数轴、刻度、曲线名称等，参数是 options 不包括data部分。

请注意，该方法不会重绘曲线就立即修改刻度标签及曲线名称，因为这些属性是以DOM节点的形式来实现的

   在canvas标签内实现的属性，比如刻度线，你需要调用draw()方法来重绘在canvas标签内实现的属性。

应该注意，如果原来图表上没有的数轴，在setupGrid()设置之后出现该数轴，那么该数轴会叠在Grid上。

5. draw()重绘图表的canvas

triggerRedrawOverlay()添加一个覆盖在图标上的canvas，这个方法对图表插件的开发非常有用，特别是一些动态的交互性的设置

           比如弹出一个下拉菜单或增加一个亮点。

           这个方法不会立即绘制设置的canvas内容，绘制的时机可以通过设置延时或鼠标事件来触发。

6. width()/height()获取图表栅格的宽和高，宽高值会比canvas和占位符的尺寸小。

7. offset()  获取图表的绘制区相对文档的坐标，鼠标事件触发获取的文档坐标减去该坐标将得到当前位置相对于绘图区的位置偏移。

   offset().left , offset().top 获取左偏移和顶部偏移。

8. pointOffset({x: xpos, y: ypos })

获取某个数据点位置相对于占位符的偏移。注意，不是相对canvas,而是相对于DIV

 可以为数据点的值注明采用的数轴，默认采用第一坐标系。

pointOffset({ x: 3, y: 3.5}).left  pointOffset({ x: 3, y: 3.5}).top  分别是数据点(3,3.5)位置相对于容器DIV的偏移。

 

下面是一些获取图表相关属性的方法：

1. getData()获取plot(placeholder, data, options) 函数的data 和 options 合成的数据。

getData() 并非仅仅返回函数的 data 参数，他是一个数组，里面的信息包含了这个曲线的信息，

    包括options,每一条曲线的每一个参数设置、包括默认设置的值及格式函数

    注意与setData()的参数区别，oo.setData(data), 则 data!= oo.getData()。

    例：

           var series = plot.getData();

           for (var i = 0; i <series.length; ++i) alert(series[i].color);  //逐个弹出曲线的颜色。

2. getAxes()该方法返回数轴信息的json对象，该对象有四个成员，分别为xaxis, yaxis, x2axis, y2axis 四条数轴

数轴内部包含了各种信息(具体信息可以把json对象转化成字符串细看，这里不细述，本文后面有将json对象系列化成字符串的方法)

例如获取X轴第一个刻度标签： getAxes().xaxis.ticks[0].label

3. getPlaceholder()获取图表容器div，返回的是一个json对象。

4. getCanvas()获取绘制区canvas，返回的是一个json对象。

5. getPlotOffset()获取栅格边缘与canvas边缘之间的距离，有数轴的一边间隔会大一些，因为需要缩小栅格防止数轴叠加在栅格上。

该方法返回一个json对象，形如 {left:36,right:6,top:6,bottom:20}。

6. getOptions()获取绘制函数的options参数，返回的是一个json对象

 

-------------

事件钩子

-------------

除了各种方法，flot还提供一些事件钩子，你可以在图表绘制过程中为事件钩子设置回调函数以修改图表绘制过程，这些回调函数具备使用flot内部数据结构的权限。

下面是flot绘图的步骤：

1.  初始化引入的插件(如果有的话)设置，解析options的参数设置

2.  创建canvas标签

3.  设置数据：解析数据设定，确定曲线颜色，把原始数据点的数据格式化成曲线所用格式，确定数轴的长度及缩放比例

4.  栅格设定：计算数轴刻度及刻度标签，设置曲线名称

5.  画图：画出栅格及曲线

6.  设置用于交互的监听事件函数

7.  如果存在的话，触发事件