Flot使用文档

最近正在使用JQuery的flot进行画图，但是这方面的中文帮助实在是太少了，干脆把英文的document直接翻译一下吧。
调用plot函数的方法如下：
var plot = $.plot(placeholder, data, options)
其中placeholder可以是JQuery的对象，DOM元素或者JQuery的表达示，要把完成的图放到这个位置上。placeholder要有宽度和高度。因为plot会修改placeholder的一些属性，所以建议大家使用一个简单的div，除了高度和宽度其它的属性都不要设置。
Data的结构：
data应该是data series的一个数组：
[ series1, series2, ... ]
一个series可以是原始数据或者是拥有属性的对象。原始数据是一个二维数组：
[ [x1, y1], [x2, y2], ... ]
为了简化flot内容的逻辑关系，x轴和y轴的数值都要使用数字（当然，如果有特殊需要的话，flot也可以支持以时间一个轴，后面会有详细的说明）。因为大多数的情况下，我们都是从数据库中直接提取数据并转换成JSON格式，但是没有关心过数据类型的问题。如果出现了奇怪的现象的话，请先检查数据的格式是否有问题。
如果在一个点的数据使用的是null的话，那么在绘制的过程中就会把这个点忽略。那么包含这个点的那条线就会有断开的现象。这个点之前和之后的点是无法进行连接的。
线和点是相关连的。对于bars， 可以设置第三个关联值（默认是0）。
一个单一的序列对象结构是：
  {
    color: color or number
    data: rawdata
    label: string
    lines: specific lines options
    bars: specific bars options
    points: specific points options
    xaxis: 1 or 2
    yaxis: 1 or 2
    clickable: boolean
    hoverable: boolean
    shadowSize: number
  }
除了其中的data以外，其它的属性都没有必要明确的指定，因为大多数情况下它们都是使用默认值的。通常你只指定标签和数据：
  {
    label: "y = 3",
    data: [[0, 3], [10, 3]]
  }
  label是说明这一个数据序列的含义的，如果只有一个序列的话就没有必要设置这个属性。如果有多个序列，就要设置label，从而可以在图中区分出序列的含义。
  如果不设置color，那么会自动生成color来进行显示。
  如果你想让用户添加和删除数据序列的话，剩下的属性就非常有用了。
  xaxis和yaxis选项设置使用哪个维度，默认是设置成1的，如果设置成2的话，就使用第二个维度（x轴在上面，y轴在右边）。
  clickable和hoverable可以设置成false，当整个图表设置成可交互时，这个选项可以让这条特定的数据序列让用户无法交互。
没有说明的属性会在后面详细介绍，大多数情况话都是使用默认值。当你要使用自己定义的值时，就会把默认的值给覆盖。
这是一个比较复杂的数据序列定义：
[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },
    { label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]
Options的含义：
所有的选项都是完全可选的。如果想要修改的话，把它当作一个对象来处理就可以了：
var options = {
    series: {
      lines: { show: true },
      points: { show: true }
    }
  };
可定制说明部分的用户设置：
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 and 1
    container: null or jQuery object/DOM element/jQuery expression
  }
说明可以看成是一个表格，由两部分组成的：一个是所有数据序列的label，另一个是颜色。如果想让label以其它的格式显示的话，可以使用lavelFormatter这个函数：

view plaincopy to clipboardprint?

1. labelFormatter: function(label, series) { 
2. // series is the series object for the label
3. return '<a href="#' + label + '" mce_href="#' + label + '">' + label + '</a>'; 
4. } 

noColums是要把这个说明部分划分成几列。position是要把这个说明放到图表的哪个位置(top-right, top-left, 等等)以及与其它图表之间的距离。backgroundColor和backgroundOpacity是设置背景的颜色和透明度，正常都是默认的。
如果你想把这个说明部分从图表中拿到来，并放到DOM中的一个元素中的话，就可以设置container这个属性，它可以是一个JQuery的对象或者表达式。psition和margin等等的一些属性就会被忽略，而且这个元素中的内容会被重写的。
关于轴的用户设置：

xaxis, yaxis: {
    show: null or true/false
    position: "bottom" or "top" or "left" or "right"
    mode: null or "time"

    color: null or color spec
    tickColor: null or color spec
    
    min: null or number
    max: null or number
    autoscaleMargin: null or number
    
    transform: null or fn: number -> number
    inverseTransform: null or fn: number -> number
    
    ticks: null or 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

    labelWidth: null or number
    labelHeight: null or number
    reserveSpace: null or true
    
    tickLength: null or number

    alignTicksWithAxis: null or number
  }

  所有的都包含相同的属性。下面会详细的介绍每一个属性的含义。

show：如果不设置这个属性的话，flot会自动的来选择，比如：数据与轴有关系的话，那么就会把轴显示出来，当然更灵活的方式还是用

           true或者false来设定这个属性。

position:用来定义轴文字显示的位置，是在X轴的上方还是下方，是在Y轴的左边还是右边。

mode：轴的数据类型，默认的是数值类型，当设置成time类型的话，就可以用时间做为一个轴。
color：定义轴标识文字和坐标的颜色。如果不设置的话，就与图表中网格的颜色是相同的。当然也可以自己来设置颜色，使用"tickColor"还

           可以单独定义坐标的颜色。

min/max：描述轴最大值和最小值范围。如果不设置的话，flot会自动的计算并生成一个范围来进行显示。

autoscaleMargin:这个有一点难理解。flot自动计算min/max的范围的时候会加上一个值，从而防止有的点会放到图的边缘。这个属性只能

                           在不设置max/min的时候才可以使用。如果设置了一个margin，flot会延长轴的结束点从而构成一个完整的坐标。默认

                           的设置是x轴没有margin，y轴有0.02的margin。默认的设置已经可以满足大多数的使用了。

"transform"，"inverseTransform"：可以对原始的数据进行一些特殊的计算以后再进行绘制。比如：可以通过这种方法来绘制一些非线性

                   的曲线。例如：
                   xaxis: {
                           transform: function (v) { return Math.log(v); },
                           inverseTransform: function (v) { return Math.exp(v); }
                   }
                  同样的，想对Y轴做反转的话就可以：
                  yaxis: {
                         transform: function (v) { return -v; },
                         inverseTransform: function (v) { return -v; }
                   }

                   Flot中的数据都是单调的，也就是说原始的数据是不能出现乱序的。inverseTransform就是transform的反向函数，通过显

                   示的数据可以得到原始数据，如果图表没有交互过程的话，这个属性可以不用设置。

      剩下的选项都是处理刻度的。如果不对刻度进行任何的设置的话，坐标生成函数会自动的计算刻度。算法会先估算刻度的个数，再计算出两个刻度之间的间隔大小，从而可以生成完整的刻度了。你可以给算法设置刻度的个数("ticks")，算法会根据原始数据的范围返回一个最接近你设置的刻度数的一个值，也就是说如果你设置了3,那么它返回5个坐标也是很正常的，因为算法认为5个刻度会更合适。如果不设置刻度的话，把"ticks"设置成0或者空数组就可以了。还可以通过设置"tickSize"来定义两个刻度之间的差值，如果设置成2,那么刻度就会是2,4,6. 通过"minTickSize"可以设置两个刻度差值的最小值。对于时间刻度，我们可以设置数组来完成：[2, "month"]。

     最狠的方法还是直接忽略flot自带的算法，完全使用数组自己定义的刻度：
             ticks: [0, 1.2, 2.4]
     下面的方法会更加的可定制化：
             ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]
      Flot还支持更牛X的可扩展性，就是可以调用一个函数来形成各个刻度的值。在函数中需要通过最小值，最大值和自己设定的一个间隔来计算出一个数组，作为各个刻度：
   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;
    }

    还可以设置"tickDecimals"来指定刻度显示的精度。

    给"tickFormatter"定义也一个函数可以灵活的格式化刻度的显示，函数有两个参数，一个是刻度的值，一个是轴上的最大值和最小值，返回值一定要是string类型：
function formatter(val, axis) {
    return val.toFixed(axis.tickDecimals);
  }

对于一个轴对象，有min和max这两个属性，还有"tickDecimals"是坐标显示的精度，"tickSize"是两个刻度之间的差值，有了这么多的属性，就可以自己定制刻度的显示内容：
function suffixFormatter(val, axis) {
    if (val > 1000000)
      return (val / 1000000).toFixed(axis.tickDecimals) + " MB";
    else if (val > 1000)
      return (val / 1000).toFixed(axis.tickDecimals) + " kB";
    else
      return val.toFixed(axis.tickDecimals) + " B";
  }

"labelWidth"和"labelHeight"是定义刻度显示区域的。"reserveSpace"的意思是即使你不定义轴，flot也会使用这个属性把轴占用的空间给预留出来。当绘制单行多轴图表时与"labelWidth"和"labelHeight"一起使用会得到很多的效果。

"tickLength"定义坐标刻度的长度，null是默认设置，也就是一个很小的刻度，如果设置成0,在轴上就不会显示刻度。

"alignTicksWithAxis"：如果设置成其它轴的数字，Flot会在自动生成刻度的时候会与其它轴上的刻度对齐的。这样会更加的美观，尤其是图中有网格，并且有多具轴的时候，非常的实用。

绘制多个轴：
      如果你需要绘制多个轴的话，数据序列就要按照下面的格式给出，{ data: [...], yaxis: 2 }表明这个序列要使用第二个Y轴。这时要设置轴的显示形式的话，就不能直接使用xaxis/yaxis的选项了，而是要有两个数组：
{
    xaxes: [ { position: "top" } ],
    yaxes: [ { }, { position: "right", min: 20 } ]
  }
  如果所有的Y轴都想设置成相同的值的话，使用yaxis: { min: 0 }就可以了。

时间类型的数据序列：
时间序列比数据序列就有一点难了。因为时间序列并不是按照10进制来排列的，所以Flot需要把时间转换成数值，再进行处理。Flot是通过javascript中的timestamps来支持时间序列的。timestamp是一个时间距1970年1月1日00:00:00的毫秒数，类似与Unix系统中使用的timestamps，只不过javascript的单位是毫秒，unix的意单位是秒。可以通过下面的来获取浏览器的timestamp：
alert((new Date()).getTime())
一般来说，大家都希望在网页上显示本地的时间，但是Flot只能把timestamp转换成UTC的时间来显示，所以唯一的方法就是获取本浏览当前的timestamp，和时区，再对timestamp的值进行计算，从而得到UTC时间与当前时间相等时的UTC timestamp。再把转换后的值提供给Flot来绘图。
这时就可以用转换后的timestamp来构造原始的数据的，并把轴的类型定义成"time"，Flot就可以自动的计算刻度并格式化它们。当然了，也可以自己定义刻度，但是一定要使用数值型的参数，不能是对象类型。刻度的生成和格式化也可以通过轴的选项来自定义：
  minTickSize: array
  timeformat: null or format string
  monthNames: null or array of size 12 of strings
  twelveHourClock: boolean
"timeformat"：时间的显示形式：
xaxis: {
    mode: "time"
    timeformat: "%y/%m/%d"
  }
  时间刻度就会显示成"2000/12/24"，具体的格式定义参考下面：
  %h: 小时
  %H: 小时 (左边补0)
  %M: 分钟 (左边补0)
  %S: 秒 (左边补0)
  %d: 日, 用 %0d 来左边补0
  %m: 月, 用 %0m 来左边补0
  %y: 年 (4位数)
  %b: 月的名字 (英文名字)
  %p: 12小时投制显示(am/pm), %h/%H
  %P: 12小时投制显示 (其中的AM/PM)

月份的名字是可以自定义的：
monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]
当"twelveHourClock"被设置成true时，时间就会用12时制来显示。